At 2017-04-20T09:39:42+0200, Guillem Jover wrote: > On Wed, 2017-04-12 at 11:00:20 -0400, G. Branden Robinson wrote: > > The former. You'll never see a C library interface manpage with > > double-colons in the name, and C++ programmers never write manpages > > because their programming language is completely intuitive. >cough< > > Well, within the perl world, I'd go as far as considering missing > documentation as malpractice. :)
Yes. Unfortunately, POD is too, at least the last time I looked at it. > Right, although given that the current markup is already mixed, and > that I'm planning anyway to switch all man pages to use POD as source, D'oh! > because the unreadability of troff also affects translators, among > other issues, this does not matter much, and in fact makes the > conversion easier, so I've left it as is. :) There is a subset of troff with the an macros that should be as easy for translators as POD is. > <https://lists.debian.org/debian-dpkg/2016/09/msg00008.html> The list of reservations you have with pod2man here seems pretty serious. > Nah, adequate; IMO, there's never enough nitpicking! ;) :-D > Attached a revised patch. Thanks! > +Any line that consists entirely (i.e., no leading whitespace) of \fB#\fP > +or \fB/* */\fP style comments, RCS keywords, Vim modelines or Emacs local > +variables should be ignored. I'll reiterate that that the an macro B would be better here, if I persuade you to block out the siren song of POD. :P One felicity that I just learned about today is that the only actively-maintained alternative troff implementation, "Heirloom Troff", has been extended to support a lot of groff's own extensions. Of particular interest: Most groff extensions, like long names for requests, strings, and number registers, are supported. A special groff compatibility mode is also provided.[1] An essential part of that long-name support is the vastly superior syntax for character escapes, even for traditional short escape names. So if you need "shaped" quotation marks, you can say: \[oq], \[cq], \[lq], \[rq] instead of \(oq, \(cq, \(lq, \(rq. This is far easier on the eye--especially so with lexical highlighting that puts a nice bright color on closing brackets, and perhaps more importantly, it makes the words immediately abutting these symbols recognizable by spell checkers. Vim's spell checker, for instance, flags "lqprotected" in "\(lqprotected\(rq" as an unrecognized word. (The spell checker still griefs you on the names of the escapes themselves, of course, but there are relatively few of those that one would want to use in a man page, and they can be disregarded, or put onto an internal or external word list much more easily.) What sort of help do you need to lower the *roff manpage burden enough that you'll keep it? I'm here for you. :) Regards, Branden [1] http://heirloom.sourceforge.net/doctools.html
signature.asc
Description: PGP signature
