[apparmor] [patch] parser/apparmor.d.pod: fix manpage formatting issues

[Steve Beattie]

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
    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).

> (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,
thanks.

-- 
Steve Beattie
<sbeattie at ubuntu.com>
http://NxNW.org/~steve/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20150602/c690424c/attachment.pgp>