Re: [install manual] Some comments about doc/manual/ files
> here are some comments and questions about doc/manual/ files:
> * The trailing dollar in $Id$ keyword is almost always lacking
Ah, that's what it is. Thanks.
> * Many files have no $Id$ keyword
I'll fix those too.
> * When applying validate.sh.patch, one can validate a single file,
> but it must be run in the file directory, e.g.
> $ cd en/hardware && ../../validate.sh hardware.xml
> I also had to move entity declarations from install.en.xml to a
> new file entities.ent
Excellent, thank you.
> * Why is this manual split into small pieces?
Small locgical pieces are more work up front, but less work to
maintain. It's easier to work on them, easier to see how diffs apply,
etc. etc. I put each <sect1> in its own doc, and then when there are
significant discussions within a sect1, which fits into several
logical pieces, I split that up into their own docs in a subfolder.
This most often happens when there are parallel discussions for
different architectures, and that has the further advantage of making
it easier for architecture-oriented folks to make changes
independently.
> * and the most important one: in XML, marked sections are only valid
> in DTD and not within XML documents! It might not be a problem if
> nsgmls is used to process these files, but XML tools will complain.
Yes, I had a note in the README acknowledging that. I hope the next
XML version has something that takes the place of marked sections,
because I don't see how we could do this doc without them. (Well, the
alternative of putting 11 docs together with 80% identical content is
just gruesome.)
nsgmls does do it correctly, so I'm hoping we can cobble something
together as a preprocessor for XML which will realize the marked
sections. I believe sgmlnorm will realize the marked sections, and
since we will have balanced tags anyway, it shouldn't affect the
document in any other way? I need help on this.
Thank you for the validate.sh improvements!!
--
Debian GNU/Linux Operating System
By the People, For the People
Chris Tillman (a people instance)
Reply to: