Re: info2html and Texinfo (Re: Linux Documentation Infrastructure)

[Sandy Harris <sandy storm ca>]

Karl EICHWALDER wrote (on gnome-doc, cc'd to me):
 
> [I don't like the X-posting idea.]

Nor I. I'm cross-posting to two lists the original message went to
(which I feel I should do so no-one interested misses out), then
setting followup-to: in hopes of pointing future discussion to one
place.

> Sandy Harris <sandy@storm.ca> writes:
> 
> |   There's an info2html tool available too.
> 
> i2h is a work around only; only fixed font output, no pictures.
> `tex2html' (or , once improved, `makeinfo --html') are much better.

Better tools than the one I knew about. Great.
 
> |      Persuade FSF that info is obsolete and should be replaced?
> 
> Please, respect other people's decision; quite a lot authors like to
> write documentation using Texinfo.

My point was that if you want a single /delivery/ format, Kim's list
wasn't enough because it couldn't easily include all the existing
docs whose source is in texinfo format.
 
> |  Writing any automated info2whatever conversion toll would likely
> |  involve considerable work.
> 
> Never rely on the info _output_; you've to work with the Texinfo source
> files (.texi).

This is just a terminology error on my part. I said "info" since that's
how I browse those files, and should have said "texinfo".

>  Join the Texinfo mailinglist if you're interested in
> writing a texinfo2xml converter as a backend of makeinfo.
> 
> In addition please note that some of us prefer to browse the Info tree
> (with Emacs)

The question on the table, I think, is how to deliver all docs for
Linux or other open source OS's in a single integrated format.

No-one is suggesting doing away with other formats. Man pages would
remain available via the man command, texinfo via info or printed via
tex, docbook in all its formats, ... The question is how to also
deliver everything one some integrated accessible-to-all way.

> and dislike HTML files a lot (browsers don't have the
> ability to search through _all_ the files at once).

That's one of the things we'd have to build for HTML to make this work.

At the very least,

   someone would need to improve my tools that give a permuted index
   from <h?> tags in a set of HTML files to production quality

   we'd need an HTML-based equivalent of man -k, likely with extensions
   for docs not in man format

   a number of overview or index files linking things together would
   need to be written

> That's why we are
> interested in docbook2texi or docbook2info as well -- a promissing
> project is already started.

I don't think the universal delivery format can be info. To do that
you'd need man2info as well as docbook2whatver, plus an info browser
that's accessible to all. 
 
> ... I recommend to
> be a little bit patient and to wait until some W3C "standards" are
> finished (XLink, XPointer, XPath, XHTML -- hope I get the names right)
> and to do all the linking using XML tools; it looks as if most of these
> "standards" will be available next time this year.

I'd prefer XML as well, but I'm not certain we can afford to wait. I'd
say do what we can now with HTML, keeping in mind that we don't want
to do anything that will make the XML conversion harder.

> Also it's important to sort out wrong placed docu (I don't see the point
> why there's a need to write a PostgreSQL or a CVS Howto and to
> distribute it with the specialized _Linux_ Howtos...).

I agree, though I can see e.g. including standard CVS docs in a Linux
distribution and having a Linux HowTo that covers any Linux-specific
stuff required to get it installed or to administer it.

I'd go further and say that any tools developed for a single delivery
format project should target at least *BSD as well as Linux.