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!)


Greg Harvey <Greg.Harvey@thezone.net> writes:

> "Greg J. Badros" <gjb@cs.washington.edu> writes:
> 
> > Greg Harvey <Greg.Harvey@thezone.net> writes:
> > 
> > > Maciej Stachowiak <mstachow@alum.mit.edu> writes:
> > > 
> > > > 
> > > > I can sympathize with the complaints about the way the markup looks, but I
> > > > think that's something we can live with. Docstrings don't need a huge
> > > > amount of markup internally.
> > > > 
> > > > Of course, TexInfo is the official documentation format of the GNU project,
> > > > so we must ensure that the tools we believe will do the conversion work as
> > > > expected.
> > > 
> > > 
> > > A better approach that could keep all of us happy :) might be to
> > > define a simple set of tags that'll handle any formatting we might
> > > want for docstrings. We really don't need the kitchen sink of docbook
> > > (nor of texinfo, for that matter); all that the docstrings need is:
> > 
> > I'm pretty severely opposed to developing our own complete markup
> > language.  There are always going to be places where we want to do more
> > than our custom language supports.
> 
> Like? We aren't writing a manual here; sure, someone might think "hey,

Tables.  Figures.  I don't want to define those in my custom markup
language since there are already plenty of good solutions.  As I wrote 
before, some set of common-case processor-independent markup is likely a 
good idea, but restricting users to that functionality is a bad idea.

Greg

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