[apparmor] [patch] parser/apparmor.d.pod: fix manpage formatting issues
seth.arnold at canonical.com
Tue Jun 2 22:43:01 UTC 2015
On Tue, Jun 02, 2015 at 01:35:56PM -0700, Steve Beattie wrote:
> > The * and ** entries don't line up with the others:
> It's intended to make as minimal change to formatting as possible while
> eliminating the following warnings by podchecker:
> *** WARNING: =item type mismatch ('bullet' vs. 'definition') at line 1276 in file apparmor.d.pod
> *** WARNING: =item type mismatch ('bullet' vs. 'definition') at line 1280 in file apparmor.d.pod
> *** WARNING: =item type mismatch ('bullet' vs. 'definition') at line 1284 in file apparmor.d.pod
> *** WARNING: =item type mismatch ('bullet' vs. 'definition') at line 1288 in file apparmor.d.pod
> *** WARNING: =item type mismatch ('bullet' vs. 'definition') at line 1292 in file apparmor.d.pod
> (which are warnings for entries after '*' and '**'). We can either:
Ahhh, these must be generated by newer-than-trusty pod tools.
> - get rid of podchecker, but both its warnings and errors are
> generally useful,
> - live with it, which we already do for the
> *** WARNING: No items in =over (at line 45) / =back list at line 272 in file apparmor.d.pod
> warning, though I'd like to come up with a way to address that
> one, too,
> - work around it, like I tried to do in the patch. One option
> would be to enclose each of the glob types in " ". Another option
> would be to indent everything by a space so all the items would
> line up with each other, if not with the surrounding explanatory
> text, so would lessen the OCD irritative nature of the change.
> I tried escaping via E<42> but that still generates the warnings.
> - switch to a less limited markup language for our man pages (and
> perhaps other documentation).
Oof. I have to admit I have wondered before how much pod buys us compared
against writing groff by hand, but maybe pandoc from markdown or
restructured would be less objectionable.
Indenting everything with a space feels like a nice half-assed approach. I
like it. :)
> > (This output is generated with an alias I've written to make
> > copy-and-pasting manpages to stack overflow work better:
> > soman is aliased to `MANPAGER=cat MANWIDTH=70 man -7 --nh --nj'
> > -- but the output looked similarly funny with the default rendering.)
> I'm surprised stack overflow needs 7 bit ascii. But that's a cool alias,
I can't recall now why seven bit was preferable, but it mostly works out
except for this bit here:
Âo Mount options support the use of pattern matching but
I have no idea what's going on there...
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 473 bytes
Desc: Digital signature
More information about the AppArmor