Re: Doc Tasks (was RE: docstrings in Guile!)

[thi <ttn at netcom dot com>]

Maciej Stachowiak <mstachow@alum.mit.edu> writes:

> Clark McGrew wrote:
> > 
> > The problem is that SGML is not richer than TeXInfo which has the full
> > power of TeX behind it.  DocBook predefines a hundreds of tags in an
> > effort get around these problems, I think it's an excellent example of
> > SGML's limitations.  All of those same tags can be trivially defined
> > inside of TeXInfo.
> 
> SGML provides rich semantic markup. TeXInfo provides rich visual layout.
> In my opinion, semantic markup is much more important because it allows
> for interesting computations to be done on the documentation far more
> easily.
> 
> > In that case, we should probably be using CWEB which is far more
> > expressive that DocBook.  With CWEB there really isn't a distinction
> > between source and documentation.  Personally I find it distracting
> > but some people like it.
> 
> I don't think it's expressive in the correct way. The expressiveness of
> DocBook is in making semantic information about elements of the
> documentation easily accessible.

it sounds like there is a preprocessing step involved w/ the scwm
documentation that recognizes `foo' in some semantic context and then
marks up the text appropriately.  if that's the case, the semantic
analysis is already done outside the scope of the sgml backend, although
the sgml backend provides convenient target tags to map to.

because texinfo is extensible, we could enrich the default set of target
tags it provides to match that of sgml.  would this be really that
difficult?

the point i'm making is that the semantic analysis is done regardless of
backend, so using that preprocessor output as the API (so to speak) is a
Good Thing in that both sgml and texinfo can be used.

thi