# @DESCRIPTION: # This eclass provides a convenience src_unpack() which does unpack all [...] # Please note that this eclass handles only tarballs (.tar, .tar.gz, # .tar.bz2 & .tar.xz). For any other file format (or suffix) it will This is transformed into: .SH "DESCRIPTION" This eclass provides a convenience src_unpack() which does unpack all [...] Please note that this eclass handles only tarballs (.tar, .tar.gz, .tar.bz2 & .tar.xz). For any other file format (or suffix) it will which results in man treating '.tar...' as a command and skipping the line in output.
i wasn't escaping things originally to allow people to insert their own roff formatting, but it seems that only two eclasses have taken advantage of that. i could say "you can only use . macros at the start", but that wouldn't help here. i'm not keen on whitelisting macros that people care about, but maybe there's no other way. ^# [.][A-Z]*$ maybe Ulrich has an idea
You could map any unknown @X and @XY tokens (X, Y arbitrary capital letters) at the start of line to the corresponding . tokens. AFAICS, it would be enough to do this in eat_paragraph. Any "." at start of line could be escaped then. ("\." doesn't seem to work, though.)
That bug affects us, infra as well. We get a "error" mail every 24h because of our eclass-html generator.
Created attachment 315527 [details, diff] Patch for eclass-to-manpage.awk (In reply to comment #2) > You could map any unknown @X and @XY tokens (X, Y arbitrary capital letters) > at the start of line to the corresponding . tokens. AFAICS, it would be > enough to do this in eat_paragraph. Attached patch should do the job. > Any "." at start of line could be escaped then. ("\." doesn't seem to work, > though.) Using \[char46] for now, because I didn't find a more elegant solution.
Created attachment 316257 [details, diff] Patch for eclass-to-manpage.awk O.K., so the gawk manual says that for a literal . one should precede it with \& which is a zero width space. Updated patch is attached.
Comment on attachment 316257 [details, diff] Patch for eclass-to-manpage.awk i generally prefer to explicit about the tokens, and to let gawk do it: # Escape . at start of line #420153 if ($2 ~ /^[.]/) $2 = "\\&" $2 as for the token mapping, there are more macros than just one/two letter upper case chars. do we care about them ? what if we made it a generic escape: # %roff .SS then you could put in whatever you wanted. @@ -84,6 +84,14 @@ function eat_paragraph() { getline while ($0 ~ /^#([[:space:]]*$|[[:space:]][^@])/) { sub(/^#[[:space:]]?/, "", $0) + + # Escape . at start of line #420153 + if ($1 ~ /^[.]/) + $1 = "\\&" $1 + # Allow people to specify *roff commands directly + if ($1 == "%roff") + sub(/^%roff[[:space:]]*/, "", $0) + ret = ret "\n" $0 # Handle the common case of trailing backslashes in # code blocks to cross multiple lines #335702
Why "%roff" and not "@ROFF"?
(In reply to comment #7) because i'd have to refactor the existing code and how it handles tokens starting with @ in order to accommodate @roff correctly. using %roff allows me to cheat and ignore that :).
(In reply to comment #8) > because i'd have to refactor the existing code and how it handles tokens > starting with @ in order to accommodate @roff correctly. using %roff allows > me to cheat and ignore that :). Lame. ;-)
(In reply to comment #9) yeah. the other side was that i'm 50/50 as to whether this should be a @ token in the first place. it doesn't feel exactly like the other @ tokens, although it does feel like the @CODE one.
ok, i sucked it up and fixed the parsing logic. it always kind of annoyed me that there were two getline loops in eat_paragraph(). now @CODE is just a shortcut to "@ROFF .nf" and "@ROFF .fi". i processed all the man pages before/after this change, and they came out the same (except for the one obvious fix wrt .tar.bz2), so i'm guessing i didn't add any regressions ;). http://sources.gentoo.org/app-portage/eclass-manpages/files/eclass-to-manpage.awk?r1=1.26&r2=1.27 i also converted the existing elisp eclasses over to the new @ROFF: http://sources.gentoo.org/eclass/elisp-common.eclass?r1=1.80&r2=1.81 http://sources.gentoo.org/eclass/xemacs-elisp-common.eclass?r1=1.6&r2=1.7
Same issue exists with an ' (apostrophe / single quote) at the beginning of the line, therefore reopening. And of course it's the same fix: (In reply to Ulrich Müller from comment #5) > O.K., so the gawk manual says that for a literal . one should precede it > with \& which is a zero width space. That's the groff manual, not the gawk manual.
Fixed in git: https://github.com/mgorny/eclass-to-manpage/commit/61979ff548f39d0ad6c21b448ebc06b3b6f75b21 I'll do some more tests, and hopefully cut a new release of app-doc/eclass-manpages tomorrow.
The apostrophe problem is fixed in eclass-manpages-20210104.
