This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
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