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

[Seth Arnold]

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

I can't recall now why seven bit was preferable, but it mostly works out
except for this bit here:

KNOWN BUGS
       Âo   Mount options support the use of pattern matching but

I have no idea what's going on there...

Thanks
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20150602/b2cd024b/attachment.pgp>