[Search for users]
[Overall Top Noters]
[List of all Conferences]
[Download this site]
| Title: | Online Bookbuilding |
| Notice: | This conference is write-locked: see note 1.3. |
| Moderator: | VAXUUM::UTT |
|
| Created: | Fri Aug 12 1988 |
| Last Modified: | Mon Jul 15 1991 |
| Last Successful Update: | Fri Jun 06 1997 |
| Number of topics: | 440 |
| Total number of notes: | 2134 |
102.0. "Converting books to run ONLINE: our worst case, fyi" by REORG::SEARLE () Fri Mar 24 1989 10:33
Our group (Rdb/VMS documentation) recently finished 'converting'
source files for books in our doc set to work with the ONLINE
doctypes and the Bookreader. For most of the books, the work
involved to get them readable by the bookreader was straightforward
and not too time consuming (perhaps a day's work for a large book).
One of the writers didn't have it so easy. He estimates he spent a
week to convert his book so it worked and was of acceptable quality
online. I asked him to detail his frustrations so folks could see
what's involved when conversion is painful.
Kirk
---------------------------------------------------------------------------
1 An Experience in Converting the Rdb/VMS Guide to Database
Maintenance & Performance to the Online Doctype
by Rod Ward, Rdb/VMS writer
This was my first attempt to convert a book to the online doc-
type and the information below describes the procedures I fol-
lowed, problems I encountered, and finally some recommendations
I have for improving the process.
First, a few statistics:
This book is 720 pp. in hardcopy (postscript) form (CUP.HANDBOOK)
and has 15 chapters that contain:
o 378 <HEAD> tags
o 30 <FIGURE> tags
o 36 <TABLE> tags
o 334 <EXAMPLE> tags
First, I completed a successful build of the book using the
HAND_TEST doctype to produce a hardcopy version of the book for
Field Test 2 of Rdb/VMS V3.1. All little problems denoted in the
log file were dealt with then to make the build successful so I
didn't have to deal with these problems when converting to the
ONLINE.HANDBOOK doctype.
To start, I sat down with one of our writers who had already
converted several books and asked about the conversion process
and some of the things I should be aware of. This was very
helpful in giving me an idea of the scope of the task.
Next, I read through the ONLINE_CLEANUP.COM program (Chuck's
version that handles the situation when <P> tag occur on the
same line as the <HEAD> tag when building the symbolic name for
each <HEAD> tag).
1
I commented out the subroutine that flagged <FIGURE_FILE> tags
that needed attention because I had already done by hand what
that subroutine did and was told that it would duplicate my
effort and I would then have the problem of going into the files
and deleting the extra <FIGURE_FILE> tags that are created.
Two things concerned me as I read through the program:
1. The program didn't handle building symbolic names for <EXAM-
PLE> or <TABLE> tags, and
2. The program didn't handle the instance where <HEAD> and
<EXAMPLE> tag titles occurred on more than one line.
I had 334 examples and many instances of multiple line <HEAD>
and <EXAMPLE> tag titles.
So I knew right off, I had my work cut out for me.
Next, I converted the book by following the instructions for
running the ONLINE_CLEANUP.COM program and then read through
the lengthy .DAT file that was created to denote problem lines.
There were 315 symbolic names created leaving 63 <HEAD> tag
titles that needed attention and there were 37
tag problems. I fixed the <P> tag problems and then built the
book using ONLINE.HANDBOOK to determine the remaining problems.
The result of the bookbuild was that I basically had 397 sym-
bolic names to enter by hand before the book would ever build
successfully.
At this point I began modifying the program to get it working
for <EXAMPLE> tags. I chose a short chapter, renamed it, created
a dummy profile to work with after an unsuccessful attempt to
deal with an individual chapter. My first attempt added symbolic
names to all <EXAMPLE_ATTRIBUTE> tags; it did a nice job and got
every one, but was not too practical. Then I began to study the
program logic more carefully and realized that the task involved
changing the program logic and this was more involved than what
I wanted to deal with. I got my wife interested and she showed
2
me how I could create flags to handle the <EXAMPLE> tag problem
and just write the record for all multiline occurrences. After a
few attempts, we got it working for one line EXAMPLE> tags, but
the problem remained how to handle the instance of the multiline
example titles and multiline title heads. We determined that
the logic to handle the multiline case involved building the
prefix after locating the opening "(", then look for the closing
")" and concatenate the result to just that line of the example
title.
Well, about this time I decided that it was time to just do it
and be done with it. We had already spent an hour or two getting
the program this far and it seemed that it would take several
more hours to get the rest of what I wanted done. So I scrapped
any further work on modifying the ONLINE_CLEANUP.COM program
and spent the next two days adding 397 symbolic names by hand.
I built the book on the 3rd attempt after I discovered that
for some strange reason, the ONLINE_CLEANUP.COM actually missed
about 8 one-line <HEAD> tags and never built the symbolic names;
4 of them occurred immediately following <ENDCOMMENT> tags and
the other 4 were scattered throughout just one chapter file.
So I fixed these up by hand and successfully built the online
version.
Next, I checked for the occurrence of my examples and discovered
that they all had to be referenced to show up; I was not aware
of the fact that this was a requirement. So I had close to 334
examples to reference in some form or fashion. I got a little
depressed at this point wondering gee this is causing me to
change the way I do things from the hardcopy version to the
online version. Well, there was no way around it, it had to be
done. It took a good solid 2 days of work added to the 3 used
already, so it took 5 full days to convert the book and make it
useable in the way intended.
3
In retrospect, maybe this book was one of the more challenging
ones. However, I can't help but draw some conclusions and make
some recommendations especially for other writers who have yet
to make the big step to convert their book to online:
o I think some immediate attention should be directed to the
ONLINE_CLEANUP.COM file so it can check for the occurrence
of the following DOCUMENT tags and if needed handle building
symbolic names as needed:
- All <HEAD>, <EXAMPLE>, <TABLE>, and <FIGURE> tags
- All multiline <HEAD> and <EXAMPLE> tags.
This would have saved me a lot of time in the conversion.
o Next, the word should get out that you must reference not
just all <HEAD> tags, but also all tables, figures, and
examples if you want any hope of seeing them in your online
version other than searching through the table of contents to
get at them.
This to me is one of the better kept secrets.
o Finally, I think there should have been some documentation
available for V1.1 of DOCUMENT that describes this doctype
and the things that need attention in order to achieve a
relatively effortless conversion.
This information would probably have helped me get on track 5
or 6 months ago in terms of referencing all required symbolic
names, especially for examples as that was the time when I
originally added the 334 <EXAMPLE> tags to the files. This
is the part where writers are required to make a midcourse
change in the way they code their files which is always an
important aspect in writing.
4
| T.R | Title | User | Personal
Name | Date | Lines |
|---|
| 102.1 | | CLOSET::UTT | | Fri Mar 24 1989 17:07 | 22 |
| There are a number of helpful hints/suggestions/warnings-about-pitfalls
here but I want to point out that some of the documentation that Rod
requests *does* exist. The document that I update with every baselevel
of the bookbuilding tools documents (or tries to document) the
requirements for coding online books. This document is called
"Coding Document Source Files for the DECwindows Bookreader" and
can be copied from
VAXUUM::KITS_:[DOCUMENT.V11]WRITER_GUIDELINES.PS
(There is also a LN03 version but it is missing the figure showing
the Bookreader interface.)
This document is referenced in note 64.2, announcing the availability
of the latest baselevel.
Section 1.3, Using the <Reference> Tag, notes that "The <reference>
tag must be used to refer to formal figures, tables, example,
and other text sections."
Mary
|
| 102.2 | I'm impressed | STAR::ROBERT | | Sat Mar 25 1989 04:53 | 22 |
| Not to in any way diminish either the effort or the frustration described
in .0, I'd nonetheless almost like to publish this note as marketing
material for the whole system.
It was our goal that books be convertible with minimal effort.
A day to convert a typical book (not "too" time consuming?) ...
I think that's great! And even a week for a 750pp manual isn't
daunting. (Well, especially if you're not the one to do it ;-)
It's a great message that we can take to customers when we encourage
them to put their books online. Believe me, alternate designs could
have been so much worse and we'd be talking about weeks or even months
to convert things.
I think CUP and the Bookreader/writer team did a good job.
As have all the writers who've gotten their material online.
- greg
ps: but keep describing your problems because I'm sure they want
to hear about them and continue improvement.
|
| 102.3 | And another experience, less painful | REORG::SEARLE | | Thu Apr 06 1989 14:52 | 40 |
| From: QUILTS::LIZ "Liz Field ZK2-2/M21 381-0691" 6-APR-1989 11:22:50.91
To: SLIMY::SEARLE
CC:
Subj: a report on online doc. experience
From: OROGEN::BODGE "Andy Bodge" 6-APR-1989 09:35:47.69
To: mary
CC: art,liz
Subj: Not bad!
I put my 240-page, many-figured Architecture document into Bookreader format in
one day -- after I had redrawn all the figures in RAGS, which took a couple of
weeks of unconcentrated work. The time was broken down roughly as follows:
1/2 hour - read "Coding .. for Bookreader"
10 seconds - decide not to use ONLINE_CLEANUP.COM after seeing the
words "file truncation" in a description of it
3 hours - process 20+ chapter files, adding symbols where necessary
and creating <figure_file>(bookreader...) tags. LSEDIT key defs
helped a lot here. I also had to change the size of most figures
and add some <online_popup>s.
45 minutes - run a check copy with POST destination
3 hours - debugging. A lot of this time was spent processing.
The hard ones to find were:
- no symbol on the <glossary> tag - resulting in errors on every
<gterm> tag as well as the <glossary> tag, leading to much head
scratching.
- one <figure> tag whose caption ended with a backslash and the
symbol was on the next line. The resulting TeX error was obscure
and I had to look at the indicated line of the .tex file to find
where the problem was. If this was not a known, documented problem,
I'd still be trying to track it down.
The remaining errors were related to the .rags figures, not the online coding.
All in all, I was pleased with how well it went. "Coding ...for Bookreader"
helped a lot, and I was fortunate that the files were already pretty clean.
Andy
|