On Sat, 20 Nov 1999, Vadim Vygonets wrote:
> Quoth Philip Hazel on Fri, Nov 19, 1999:
> [HTML documentation]
> > That's because it is created by a script which generates Texinfo which
> > is passed to the texi2html script.
>
> What is the initial format? I wonder if I can find a better
> solution.
For me, the primary documentation is the PostScript for the printed
manual, complete with table of contents and usable index. That is what I
work towards - the other formats are spin-offs. I happen to care about
the appearance of printed material that I produce - I want decent
paragraph formatting, sensible hyphenation (and not too much of it),
avoidance of 'widow' and 'orphan' lines on pages, use of ligatures (fi
etc) in fonts, easy-to-maintain line graphics, automatic maintenance of
cross references, change bars, and of course automatic chapter/section
numbering and indexing. I also want to be as consistent as possible in
the layout and typography.
Of the two sets that humans fall into, I happen to be a 'describer'
rather than a 'doer', so I prefer to use my favourite text editor to
prepare marked up text rather than anything WYSIWYG. So, the base
documentation is a set of text files marked up for SGCAL, a text
formatter that I wrote about 20 years ago. (Think TeX, but it doesn't do
mathematics.) From this the PostScript and plain text documentation is
produced directly. Initially, those were the only formats supplied. Then
the GNU people asked about Texinfo, which is their standard. I wrote a
Perl script to turn the source into a Texinfo file. I resisted their
requests to make this the primary source because it lacks things I think
are important, such as change bars and the sort of cross-referencing I
wanted. Then somebody wanted HTML, and the texi2html script was pointed
out to me by Nigel, who did an initial set of modifications to my Perl
script to introduce a few tweaks for the HTML case. That is why the HTML
version comes from Texinfo and not from the original.
A better result would no doubt be obtained from a script that turned the
source directly into HTML. It could provide chapter and section numbers,
for example. Maybe something better could be done with the graphics.
Maybe one day...
--
Philip Hazel University of Cambridge Computing Service,
ph10@??? Cambridge, England. Phone: +44 1223 334714.
