[apparmor] [patch] parser/apparmor.d.pod: fix manpage formatting issues
steve at nxnw.org
Tue Jun 2 20:35:56 UTC 2015
On Tue, Jun 02, 2015 at 11:43:41AM -0700, Seth Arnold wrote:
> On Tue, Jun 02, 2015 at 10:17:44AM -0700, Steve Beattie wrote:
> > - added preceding space before the '*' and '**' explanation =item
> > entries; without these the list would get treated as a bullet list
> > and then the pod tools would complain that the later entries were not
> > bullet list items (added a comment to explain as well)
> > -=item B<*>
> > +=item B< *>
> > can substitute for any number of characters, excepting '/'
> > -=item B<**>
> > +=item B< **>
> > can substitute for any number of characters, including '/'
> > @@ -1349,6 +1357,8 @@ with the I<allow> qualifier.
> > Specifies that the task must have the same euid/fsuid as the object being
> > referenced by the permission check.
> > +=back
> > +
> Most of this patch is really good but this change seems awkward; it
> causes the rendering to look funny in the terminal and doesn't change
> the HTML output when rendered by firefox.
> 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:
- get rid of podchecker, but both its warnings and errors are
- 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
- 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).
> (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,
<sbeattie at ubuntu.com>
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 819 bytes
Desc: Digital signature
More information about the AppArmor