Re: Header nesting style question

Tue, 12 Jul 94 13:21 BST

Chris lilley writes @ Tue, 12 Jul 1994 13:58:00 +0200

>In message <>, Ken Fox writes:

>> Hmm... another style question: Do people prefer one giant
>> document with internal references, or many small documents with external
>> references?

>The latter. You might not want to read all of it, so you only pay the
>network lag for the bits you want to read.

Doesn't this depend, at least to some extent, on the documents themselves.
Project gutenberg provide *large* texts and, to judge from some of the
replies to this list, there is demand for them. I, for example, am using
our hcsa httpd to serve master documents (still under development) from a
backend mixed relational/full text database. Some of these are large and
some are small. None of them exist in the form they are actually viewed.
The network lag is a problem but still, the size of a document is a feature
of a document not a browser or a network. If we defer to browsers and
networks here then the larger project - the free distribution of
information and knowledge (same thing? - no) around the world.

>[I wrote]
>>> Some options you have for the section files:
>>> 1) use h1 for the previous chapter head and h2 for the section heads
>>> ...
>>> 2) use h1 for the section titles, and a paragraph for the chapter titles
>>> ...
>>> 3) Use h1 for chapters, h2 for sections, h3 for subsections etc as if it
>>> were all one monolithic document, but cut into pieces.

>> There are a lot of different ways of doing it. I was kind of wondering
>> what a nice consistent reader-friendly way of doing it is...

>That was the purpose of the comments that you have edited out. In case it
>was not apparent, the second way was the one I was suggesting as being the
>most consistent and user freindly.

>>> You are. You're going to do it manually, aren't you. No no no no

>> What does manually mean? [sarcasm deleted]

>Manually means applying basic software engineering principles - avoid the
>cut and paste school of programming. If, conceptually in the monolithic
>document, you have a chapter title "Mating behaviour in ducks and geese" you
>only have that _once_ in the revisable form of the document.

>Doing it manually means that you type that string into each and every
>document that uses it as an anchor. It means that when you later change it
>to "Mating behahaviour in ducks" you have to manually go through and edit
>each instance of the chapter title. It means that you inadvertantly miss one
>out, and that one subsection in the ducks chapter still refers to geese ...

>Doing it automatically means that you prepare the document in one form then
>apply rules - with a makefile, using cpp, awk, whatever - to generate the
>final form. It means that the resulting document is maintainable, accurate,
>and easy to read. Given that your .sig talks about CAD/CAM/CAE process
>integration I expected you to be very familiar with these concepts.

Well, I have "p" for programmer in my account name ...

Still, the central point is absolutely correct. Manual maintenance of
large document stores is bound to result in errors and inaccuracies. This
is what computers are *for*. They do billions of almost meaningless, dull,
repetative tasks in the blink of an eye (well the odd Cray might ...;).
Maintaining an up to date set of links in a datastore is a *doddle* for
them. Use the tool that fits the job.

>> There's nothing to convert because the document doesn't exist.

>So write it, then... puzzled.

>> OH! You mean "don't use HTML to write your document because it's not
>> expressive enough."

>No, actually, although that is certainly an option.

>> You seem assume that given structure, you can emit style

>Given structure you can emit documents conforming to the layout rules you
>have chosen. Whether that is a suitable choice for a particular document is
>of course up to you.

Standards, ah, standards. Somebody pass me our SLA ...

Al. <-:< (