Re: Source Text Tools

[Tim Teulings <tim@edge.ping.de>]

Hallo!

> Texinfo is powerful enough.  You might check out the printed version
> of the OOC Reference Manual.  Or the info version.  Or the HTML
> version.

Texinfo is fine, I know. I have written a number of documents with it.
F.e the VisualOberon documentation. However - as I told above - it is
not good for heavy cross-referenced stuff. That's because there are a
number restrictions about where to set a link (Also the info output
using links in emacs looks *very* ugly). As I told, use Texinfo if
you like (or a tex-like grammar), but don't expect it to be convertable
to real texinfo without problems. Implicit linking *might* help.

> Suggestion: Implement a tool to convert an unmarked text into one with
> explicit meta information.  Then we coule simply use it as a
> pre-processor for all the other programs dealing with doc comments.

No problem. Autodoc already did some of that stuff. However it did it
only for module-intern stuff. It you want you to automatically link to
stuff in other modules you must feet them in at once and you must work
in two parses (a recursively). Howver it is no problem to build a
global symbol table and do a textmatch for each word in a comment
(while this may be slow). Interesting is, while autodoc generated texinfo
output and automatically detected declared objects within the description
it did not link them (while it could) that was because of said
limitation in texinfo which restricted the placing of references. That
was one main reson why I looked for SGML as alterative. because it
enabled as less restrictive solution. Most of the commercial tools do
it that way, too.

> Using explicit type setting commands would be a _huge_ step backwards.
> The Texinfo commands provide meta information which is turned into
> suitable formatting for various output devices.  Going back to the
> type setting level would discard all the benefits of HTML or Texinfo.
> Besides, you can't build proper Texinfo files from such low-level kind
> of text.

There are much better formatting tools than texinfo. Use sgml which
more explicitely devided between look and abstract descripion. Take a
look at SGML-tools I can give the link. SGML-Tools can generate HTML,
texinfo, info, man-pages!, TeX, ps... I proposed that solution, not
because I think it is the best, but because it is restricted enough and
like easy to handle. I know at least one commercial tool, that
generated reasonable output (HTML) out of that. And yes, autodoc
generated proper texinfo for a subset without problem.

To answer anoher question in the list: SGML-Tool come with their own
documenttype linux-doc. Which is powerful and support as much as
texinfo. I did not use it because there were some bugs in and I wanted
to wait until they were fixed. I haven't check the last two versions
because of lack of time. I also subscribed the mailinglist and it
seemed there was heavy discussion about the future way of SGML-Tool.
However it seemded clear that the linux-doc style would be supported
for a long while (The whole/most of the HOWTOs of the linux
documentation project are written with it). Using SGML for formatting
would be very easy because you can leave *all* formatting (possibly
except autogenerated links) to an external program.

-- 
Gru...
       Tim.