gdoc replacement (was: Re: Default record version)

[Martin von Gagern]

Simon Josefsson schrieb:
> I am a bit reluctant to do major work on the current gdoc -- if major
> work is going to be done (which would be great!), what I would prefer
> would be a clean re-implementation of it, that would be copyrighted by
> the FSF, and thus could be added to gnulib.

Sounds reasonable, even though I havent dealt with gnulib before. In my
opinion, a formal description of the grammar used in comments should be
the first step along that road, and the basis for discussion. Shouldn't
be too complicated, but it might help get some things straight.

Once you have that in place, using common lexer and/or parser generators
should be enough to do most of the work on the input side. Of course,
this approach is more easily turned into a C program than a Perl script,
but I assume this might even be a plus in terms of portability, as long
as you get it compiled as part of your build process or depend on it
being installed in its binary form on the build system.

> This would make it easier
> to re-use it between projects; I'm already using variously patched
> versions of gdoc in several of my projects.  This could be written with
> some design documentation, that discuss how to deal with problems like
> you have discovered.

It is my opinion that such problems should not even happen in the first
place. This means that
a) special syntax should be clearly and unabiguously recognizable as
such. E.g. in TeX, a command is introduced by \ (disregarding any other
special chars TeX uses besides \), in Javadoc by @, and so on. This way,
users know when what they type will be treated as a command, and are not
likely to involuntarily use obscure markup they never thought about.
b) All non-special syntax should be escaped wherever the output medium
requires it, avoiding issues like those special meanings for ' and %.

Of course, all of this would probably imply a change of syntax, e.g.
from %CONSTANT to {@const CONSTANT} or stuff like that. Would that be
acceptable? If you decide that a change of syntax is acceptable, it
might make sense to emulate the syntax of some other projects. The one
that comes to my mind is Doxygen, mostly because it's the only one I've
worked with before, besides Javadoc. Such a step might mean translating
fragments from some (maybe well defined) subset of HTML to other
languages. The smaller the subset, the easier this process. This would
also allow for HTML entities as a powerful means to escape special
characters.

> Meanwhile, we should be open to consider hacks that work around the
> larger problem.

Doable, given the right amount of hacking.

> If all else fails, we could post-process this
> particular man page to make it render properly.

I assume it should be possible to avoid that, at least as long as you
don't mind accumulating deviations and hackish code in gdoc.

> /Simon

Martin

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 258 bytes
Desc: OpenPGP digital signature
URL: </pipermail/attachments/20090227/d67019ff/attachment.pgp>