Re: Header nesting style question

Chris Lilley, Computer Graphics Unit (lilley@v5.cgu.mcc.ac.uk)
Tue, 12 Jul 1994 13:59:48 +0200

In message <9407111959.AA22643@pt0204.pto.ford.com>, 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.

[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.

> 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.

--
Chris Lilley
+--------------------------------------------------------------------------+
|Technical Author, ITTI Computer Graphics & Visualisation Training Project |
+--------------------------------------------------------------------------+
| Computer Graphics Unit, | Internet: C.C.Lilley@mcc.ac.uk |
| Manchester Computing Centre, | Janet: C.C.Lilley@uk.ac.mcc |
| Oxford Road, | Voice: +44 61 275 6045 |
| Manchester, UK. M13 9PL | Fax: +44 61 275 6040 |
| X400: /I=c/S=lilley/O=manchester-computing-centre/PRMD=UK.AC/ADMD= /C=GB/|
| <A HREF="http://info.mcc.ac.uk/CGU/staff/lilley/lilley.html">my page</A> |
+--------------------------------------------------------------------------+