This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

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


Clark McGrew <mcgrew@ale.physics.sunysb.edu> writes:

> >>>>> "Greg" == Greg J Badros <gjb@cs.washington.edu> writes:
> 
>     Valentin Kamyshenko <val@kamysh.materials.kiev.ua> writes:
> 
>     Greg> But if we can convert to TeXInfo from DocBook (and rumour
>     Greg> has it that the tools are there, though I've not had time to
>     Greg> try them yet), then these problems go away and we're able to
>     Greg> just use the strictly richer SGML markup.
> 
>     >> Is not it the contradiction?  If the SGML markup is richer that
>     >> TeXInfo, than it will be impossible to convert .sgml to .texi
>     >> without loosing the quality of the output, is not it?
> 
>     Greg> It's not a contradiction: we do end up losing quality of the
>     Greg> output, but only while we feel that the TeXInfo tools serve
>     Greg> our needs better.
> 
> 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.

But reasoning about those definitions is hard.  Reasoning about DocBook
tags is easy.  Dropping into TeX should not be necessary for
documentation.  TeX is a visual layout language.

> 
>     Greg> Think of it in terms of audio mastering: you want an all
>     Greg> digital perfect initial recording, even if ultimately you'll
>     Greg> distribute an analog cassette or an 56kbps mp3.
> 
> Are you arguing for or against TeXInfo?

Against as the primary stored-format for documentation.

>     Greg> But the point of Docbook markup is to permit getting any of
>     Greg> those formats from a single source by enriching that source
>     Greg> substantial.
> 
> 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.

Again, expressiveness is a tradeoff between wanting to be able to do
cool things and wanting to be able to reason about the cool things that
you've done.  SGML DocBook is a very nice point in that design space
where you can do almost all the things people care about doing for
documentation, and can still exploit the excellent semantic markup of
the text to reason usefully about the text.

Greg

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]