[apparmor] [patch] parser/apparmor.d.pod: fix manpage formatting issues
Steve Beattie
steve at nxnw.org
Tue Jun 2 17:17:44 UTC 2015
This patch fixes several formatting issues with the apparmor.d man page:
- missing formatting code prefixes, usually I for BNFish arguments
- added blank lines before preformatted sections as the html formatter
wasn't treating them as seperate from the preceding text (also, they
generated podchecker warnings)
- 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)
- fixed a grammar issue
- fixed link description text block that was mistakenly indented and
thus treated as preformatted text
- moved the "Qualifier Blocks" subsection out of the =over/=back as
all the pod tools did not like this and it caused podchecker to exit
with an error, breaking builds that ran make check on the parser
tree.
The result of 'make check_pod_files' before applying this patch:
LANG=C podchecker -warning -warning *.pod
*** WARNING: 2 unescaped <> in paragraph at line 61 in file apparmor.d.pod
*** WARNING: 2 unescaped <> in paragraph at line 85 in file apparmor.d.pod
*** WARNING: 2 unescaped <> in paragraph at line 87 in file apparmor.d.pod
*** WARNING: 2 unescaped <> in paragraph at line 234 in file apparmor.d.pod
*** WARNING: 2 unescaped <> in paragraph at line 242 in file apparmor.d.pod
*** WARNING: 2 unescaped <> in paragraph at line 256 in file apparmor.d.pod
*** WARNING: 2 unescaped <> in paragraph at line 256 in file apparmor.d.pod
*** WARNING: No items in =over (at line 45) / =back list at line 272 in file apparmor.d.pod
*** WARNING: 1 unescaped <> in paragraph at line 535 in file apparmor.d.pod
*** WARNING: 1 unescaped <> in paragraph at line 575 in file apparmor.d.pod
*** WARNING: 2 unescaped <> in paragraph at line 609 in file apparmor.d.pod
*** WARNING: 1 unescaped <> in paragraph at line 613 in file apparmor.d.pod
*** 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
*** ERROR: =over on line 1328 without closing =back (at head3) at line 1352 in file apparmor.d.pod
*** ERROR: =back without previous =over at line 1362 in file apparmor.d.pod
apparmor.d.pod has 2 pod syntax errors.
apparmor.pod pod syntax OK.
apparmor_parser.pod pod syntax OK.
subdomain.conf.pod pod syntax OK.
../common//Make.rules:172: recipe for target 'check_pod_files' failed
make: *** [check_pod_files] Error 1
The result after applying this patch:
LANG=C podchecker -warning -warning *.pod
*** WARNING: No items in =over (at line 45) / =back list at line 272 in
file apparmor.d.pod
apparmor.d.pod pod syntax OK.
apparmor.pod pod syntax OK.
apparmor_parser.pod pod syntax OK.
subdomain.conf.pod pod syntax OK.
The remaining warning is due to the BNFish language description being
indented but without each of the entries in it being listed as =items.
Converting all entries to =item would fix the warning but causes the
indention to be broken on the html man pages at a minimum.
Signed-off-by: Steve Beattie <steve at nxnw.org>
---
parser/apparmor.d.pod | 48 ++++++++++++++++++++++++++++--------------------
1 file changed, 28 insertions(+), 20 deletions(-)
Index: b/parser/apparmor.d.pod
===================================================================
--- a/parser/apparmor.d.pod
+++ b/parser/apparmor.d.pod
@@ -46,7 +46,7 @@ to the policy; this behaviour is modelle
B<PROFILE FILE> = ( [ I<PREAMBLE> ] [ I<PROFILE> ] )*
-B<PREAMBLE> = ( I<COMMENT> | I<VARIABLE ASSIGNMENT> | I<INCLUDE> )* (variable assignment must come before the profile)
+B<PREAMBLE> = ( I<COMMENT> | I<VARIABLE ASSIGNMENT> | I<INCLUDE> )* (variable assignment must come before the profile)
B<INCLUDE> = '#include' ( I<ABS PATH> | I<MAGIC PATH> )
@@ -58,7 +58,7 @@ B<COMMENT> = '#' I<TEXT> [ '\r' ] '\n'
B<TEXT> = any characters
-B<PROFILE> = ( I<PROFILE HEAD> ) [ I<ATTACHMENT SPECIFICATION> ] [ <PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
+B<PROFILE> = ( I<PROFILE HEAD> ) [ I<ATTACHMENT SPECIFICATION> ] [ I<PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
B<PROFILE HEAD> = [ 'profile' ] I<FILEGLOB> | 'profile' I<PROFILE NAME>
@@ -82,9 +82,9 @@ B<COMMA RULES> = ( I<CAPABILITY RULE> |
B<BLOCK RULES> = ( I<SUBPROFILE> | I<HAT> | I<QUALIFIER BLOCK> )
-B<SUBPROFILE> = 'profile' I<PROFILE NAME> [ I<ATTACHMENT SPECIFICATION> ] [ <PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
+B<SUBPROFILE> = 'profile' I<PROFILE NAME> [ I<ATTACHMENT SPECIFICATION> ] [ I<PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
-B<HAT> = ('hat' | '^') I<HATNAME> [ <PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
+B<HAT> = ('hat' | '^') I<HATNAME> [ I<PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
B<HATNAME> = ( must start with alphanumeric character. see aa_change_hat(2) for a description of how this "hat" is used. IF '^' is used to start a hat then there is no space between the '^' and I<HATNAME>)
@@ -231,7 +231,7 @@ B<RLIMIT RULE> = 'set' 'rlimit' [I<RLIMI
B<RLIMIT> = ( 'cpu' | 'fsize' | 'data' | 'stack' | 'core' | 'rss' | 'nofile' | 'ofile' | 'as' | 'nproc' | 'memlock' | 'locks' | 'sigpending' | 'msgqueue' | 'nice' | 'rtprio' | 'rttime' )
-B<RLIMIT VALUE> = ( I<RLIMIT SIZE> | I<RLIMIT NUMBER> | I <RLIMIT NICE> )
+B<RLIMIT VALUE> = ( I<RLIMIT SIZE> | I<RLIMIT NUMBER> | I<RLIMIT NICE> )
B<RLIMIT SIZE> = I<NUMBER> ( 'K' | 'M' | 'G' ) Only applies to RLIMIT of 'fsize', 'data', 'stack', 'core', 'rss', 'as', 'memlock', 'msgqueue'.
@@ -239,7 +239,7 @@ B<RLIMIT NUMBER> = number from 0 to max
B<RLIMIT NICE> = a number between -20 and 19. Only applies to RLIMIT of 'nice'
-B<FILE RULE> = [ I<QUALIFIERS> ] [ 'owner' ] ( 'file' | [ 'file' ] ( I<FILEGLOB> I<ACCESS> | I<ACCESS> I<FILEGLOB> ) [ -E<gt> <EXEC TARGET> ] )
+B<FILE RULE> = [ I<QUALIFIERS> ] [ 'owner' ] ( 'file' | [ 'file' ] ( I<FILEGLOB> I<ACCESS> | I<ACCESS> I<FILEGLOB> ) [ -E<gt> I<EXEC TARGET> ] )
B<FILEGLOB> = ( I<QUOTED FILEGLOB> | I<UNQUOTED FILEGLOB> )
@@ -253,7 +253,7 @@ B<EXEC TRANSITION> = ( 'ix' | 'ux' | 'U
B<EXEC TARGET> = name (requires I<EXEC TRANSITION> specified)
-B<LINK RULE> = I<QUALIFIERS> [ 'owner' ] 'link' [ 'subset' ] <FILEGLOB> ( 'to' | '-E<gt>' ) <FILEGLOB>
+B<LINK RULE> = I<QUALIFIERS> [ 'owner' ] 'link' [ 'subset' ] I<FILEGLOB> ( 'to' | '-E<gt>' ) I<FILEGLOB>
B<VARIABLE> = '@{' I<ALPHA> [ ( I<ALPHANUMERIC> | '_' ) ... ] '}'
@@ -532,7 +532,7 @@ determine the profile to transition to f
is however possible to specify the name of the profile that the transition
should use.
-The name of the profile to transition to is specified using the '->'
+The name of the profile to transition to is specified using the '-E<gt>'
followed by the name of the profile to transition to. Eg.
/bin/** px -> profile,
@@ -572,8 +572,9 @@ or trailing the file glob. Eg.
/** rw, # trailing permissions
-When a leading permissions is used further rule options and context
+When leading permissions are used further rule options and context
may be allowed, Eg.
+
l /foo -> /bar, # lead 'l' link permission is equivalent to link rules
=back
@@ -593,25 +594,27 @@ Eg.
/link* rw,
link subset /link* -> /**,
- The link rule allows linking of /link to both /file1 or /file2 by
- name however because the /link file has 'rw' permissions it is not
- allowed to link to /file1 because that would grant an access path
- to /file1 with more permissions than the 'r' permissions the profile
- specifies.
+The link rule allows linking of /link to both /file1 or /file2 by
+name however because the /link file has 'rw' permissions it is not
+allowed to link to /file1 because that would grant an access path
+to /file1 with more permissions than the 'r' permissions the profile
+specifies.
- A link of /link to /file2 would be allowed because the 'rw' permissions
- of /link are a subset of the 'rwk' permissions for /file1.
+A link of /link to /file2 would be allowed because the 'rw' permissions
+of /link are a subset of the 'rwk' permissions for /file1.
The link rule is equivalent to specifying the 'l' link permission as
a leading permission with no other file access permissions. When this
is done the link rule options can be specified.
The following link rule is equivalent to the 'l' permission file rule
+
link /foo -> bar,
l /foo -> /bar,
File rules that specify the 'l' permission and don't specify the extend
link permissions map to link rules as follows.
+
/foo l,
l /foo,
link subset /foo -> /**,
@@ -1263,13 +1266,18 @@ typically included at the beginning of a
File resources may be specified with a globbing syntax similar to that
used by popular shells, such as csh(1), bash(1), zsh(1).
+=for comment
+XXX The space before the '*' in the =item fields below is
+unfortunately needed; otherwise the various pod tools assume the
+list is a bulleted one and complain about later non-bulleted entries
+
=over 4
-=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
+
=head3 Qualifier Blocks
Rule Qualifiers can be applied to multiple rules at a time by grouping the
@@ -1359,8 +1369,6 @@ rules into a rule block.
network,
}
-=back
-
=head2 #include mechanism
AppArmor provides an easy abstraction mechanism to group common file
--
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/77c83fdc/attachment.pgp>
More information about the AppArmor
mailing list