Bugzilla Bug 184779

While trying to convert the (rather lengthy) documentation in
elisp-common.eclass to a format that can be processed with
eclass-to-manpage.awk, I discovered that the parsing of the awk script is
somewhat fragile.

Especially, I think it is not a good idea to have significant trailing
whitespace: An empty comment line will end paragraph parsing, while a comment
line containing one blank does not. (Also, trailing whitespace is not allowed
in ebuilds and the "Eclass Howto" says that eclasses have the same syntax as
ordinary ebuilds.)

Attached patch will make parsing more robust.

Created an attachment (id=124365) [details]
Proposed patch for eclass-to-manpage.awk

Following changes:
1. Trailing whitespace is no longer significant. (So an empty comment line
   doesn't end paragraph parsing anymore. Use an empty line or a line like
   "# @END" for that.)
2. Don't distinguish between spaces and TABs.
3. Canonical order of man page sections, "SEE ALSO" should be last.

Created an attachment (id=124487) [details]
Proposed patch for eclass-to-manpage.awk

Created an attachment (id=124963) [details]
Patch for eutils.eclass

eutils.eclass is the only eclass with man page documentation so far.

This trivial patch should be applied, so that it will give the same result with
the changed awk as before.

Hah! It was bound to happen:

RCS file: /var/cvsroot/gentoo-x86/eclass/eutils.eclass,v
Working file: eutils.eclass
head: 1.286
[...]
revision 1.286
date: 2007-07-17 13:59:18 +0200;  author: swegener;  state: Exp;  lines: +10
-10;  commitid: 23f6469caf084567;
Apply whitespace checks from repoman to eclasses.

swegener: you fail :p

i'll see about merging your updates this weekend, thanks

:(

do you really need all the extraneous whitespace allowance or did you add it
for completeness sake ?  i merged the obvious fix to allow paragraphs to flow
over comment blocks that lack trailing whitespace ...

Created an attachment (id=125858) [details]
Updated patch for eclass-to-manpage.awk

(In reply to comment #7)
> do you really need all the extraneous whitespace allowance or did you add
> it for completeness sake ?  i merged the obvious fix to allow paragraphs
> to flow over comment blocks that lack trailing whitespace ...

Hmm... Now eat_paragraph will terminate on a comment line containing only
whitespace, i.e. your previous syntax will not work anymore (and trailing
whitespace is still significant, but the other way around).

I think attached patch should be merged in addition. The rest (of my previous
patch) is not essential.

I just committed elisp{,-common}.eclass which contains some code snippets (we
briefly discussed it on IRC yesterday). After applying the patch from
attachment #125858 [details] this works without further changes due to the following
groff feature (section 5.1.5 "Implicit Line Breaks"):

| A line that begins with a space causes a break and the space is output
| at the beginning of the next line. Note that this space isn't adjusted,
| even in fill mode.

Especially there is no need for .nf/.fi pairs.

O.K., now there is @CODE. But AFAICS you cannot use indented code snippets
since the parser eats the indentation, i.e. the leading white space.

The patch from attachment #125858 [details] will fix it.

(In reply to comment #8)
> Created an attachment (id=125858) [edit] [details]
> Updated patch for eclass-to-manpage.awk

Any objections if I commit this change myself?

> Any objections if I commit this change myself?

Seems not to be the case - committed.