> > Hmm... another style question: Do people prefer one giant
> > document with internal references, or many small documents with external
> > references?
Chris Lilley responds:
> 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.
Browsers aren't very good at working with compound documents --- that is, a
related web of documents. Things like searching, printing, saving, etc.
don't work very well. Mosaic doesn't even save inlined images when
documents are saved as hypertext! Clearly it is possible to implement these:
fish search for Mosaic is a good example. Browsers need to improve to the
point where a reader is unaware they've crossed a "document" boundary.
Well, it should be smoother at least...
Several people have pointed this out to me. :-)
[censorship flame: I don't think we need automated censorship of articles
yet. Because my previous paragraph contained "Mosaic" it would have been
tossed back to me. Maybe not a big deal now, but once the infrastructure is
in place I can see it being abused.]
> >> 2) use h1 for the section titles, and a paragraph for the chapter titles
> ... In case it
> was not apparent, the second way was the one I was suggesting as being the
> most consistent and user freindly.
I assume that you define "section" to be "one of the units of information
that the current topic is decomposed into." Then you suggest that header
levels reflect the physical nesting of sections within the same document,
right? (Take document to mean "the contiguous unit of hypertext that gets
loaded into a browser.") You also seem to recomend that header levels
should be "reset" to <h1> with every new document.
I think this is style that looks best --- I format my documents like this.
Does this have any impact on automatic table of contents generators?
Re-using the <h1> level for chapters and sections is probably okay. It
might get confusing if logical sub-sections are ever tagged <h1>.
Chris and I differ greatly on the use of navigational components in the text.
Things like "on to", "up to", "next", "previous", etc. I personally don't
like these mechanisms because the traversal history stored in the reader's
browser often doesn't match what the author intended. This means that the
reader has to (a) ignore any browser navigation, or (b) maintain the
relationship between browser history and document structure in her head. I
think HTML+ will help solve this by providing the hints browser needs to
maintain that structure mapping automatically. I've done a simple hack to
Mosaic to associate the functions on window buttons with hyperlinks in the
text:
<a href="!backnode">Go back</a>
This would perform the Mosaic previous-page function. It worked out okay,
but wasn't complete enough to be useful. Browsers need to understand a *lot*
more about document structure...
How do others feel about navigational aids?
> >> You are. You're going to do it manually, aren't you. No no no no
>
> > What does manually mean? [sarcasm deleted]
Sorry about the sarcasm. I was provoked... 8-)
> 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.
I completely agree with you. Once I get "The Style" then I can provide the
tools that implement an appropriate level of automation. Right now, this
appropriate level is just emacs macros (which can be pretty damned
sophisticated!)
> > There's nothing to convert because the document doesn't exist.
>
> So write it, then... puzzled.
I want to stay in HTML. Ideally, I'd like to stay within pure HTML. That's
not realistically possible, so dropping back to some higher level markup
(maybe with a macro language) doesn't bother me too much. What you seem to
be suggesting is create my document in something completely different and
then do the translation to HTML mechanically. This is what I meant by:
> > OH! You mean "don't use HTML to write your document because it's not
> > expressive enough."
We often argue ourselves into agreement... Is this one of those cases? ;-)
> > 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.
I've just about finished reading a book on technical editing. It's been a
real eye-opener for me --- I thought that the editor's job was mostly
mechanical. A lot of style decisions *are* mechanical, but there needs to
be simple and effective ways to "change the rules."
- Ken
-- Ken Fox, fox@pt0204.pto.ford.com, (313)59-44794 ------------------------------------------------------------------------- Ford Motor Company, Powertrain | "Is this some sort of trick question CAD/CAM/CAE Process Integration | or what?" -- Calvin AP Environment Section |