mbox series

[RFC,selinux-notebook,00/18] markdown conversions and cleanups

Message ID 159650470076.8961.12721446818345626943.stgit@sifl (mailing list archive)
Headers show
Series markdown conversions and cleanups | expand

Message

Paul Moore Aug. 4, 2020, 1:33 a.m. UTC
This patchset helps to get us a little closer to finishing the work
of converting The SELinux Notebook to markdown.  I believe this is
a worthwhile goal for two main reasons: it makes the raw markdown
much easier to read (the HTML tables are painful in source form),
and it makes it easier to render the markdown into different formats
(currently HTML and PDF).

My original goal for this patchset was to complete the markdown
conversion before posting the series, but I now realize that was
neither a practical or good idea.  While this patchset may miss my
original goal, I do believe it is a step forward both in terms of the
raw markdown and the rendered formats, and I would suggest we merge
these changes assuming no strong objections.

For those who want to quickly check the markdown on GitHub or the
rendered HTML and PDF formats, I've included the links below:

* https://drop.paul-moore.com/21.HGW6/SELinux_Notebook.pdf
* https://drop.paul-moore.com/21.HGW6/SELinux_Notebook.html
* https://github.com/pcmoore/misc-selinux_notebook/tree/working-md_full

---

Paul Moore (16):
      build: explicitly enable pandoc pipe_tables
      css: identify table layout hacks
      css: style improvements
      x_windows: fully convert to markdown
      xperm_rules: fully convert to markdown
      xen_statements: fully convert to markdown
      vm_support: fully convert to markdown
      user_statements: fully convert to markdown
      userspace_libraries: fully convert to markdown
      type_statements: fully convert to markdown
      all: remove all the <br> tags we haven't gotten to yet
      all: unify example formatting (scripts, code, policy, etc) in markdown
      all: don't use "`" for formatting text, use "*" instead
      all: consolidate multiple blank lines into one
      kernel_policy_language: convert the footnotes to markdown
      title: assorted updates

Richard Haines (2):
      postgresql: update PostgreSQL SELinux Support section
      x_windows: don't call table 12 a table


 src/apache_support.md              |  53 +--
 src/auditing.md                    |  36 +-
 src/avc_rules.md                   |  48 +--
 src/bounds_rules.md                |  18 +-
 src/cil_overview.md                |  43 +-
 src/class_permission_statements.md |  44 +-
 src/computing_access_decisions.md  |   2 -
 src/computing_security_contexts.md | 224 +++++-----
 src/conditional_statements.md      |  36 +-
 src/configuration_files.md         |  10 +-
 src/constraint_statements.md       |  52 +--
 src/core_components.md             |  10 -
 src/debug_policy_hints.md          |   5 -
 src/default_rules.md               |  40 +-
 src/domain_object_transitions.md   | 138 +++---
 src/file_labeling_statements.md    |  58 ++-
 src/global_config_files.md         |  16 +-
 src/images/24-database-table.png   | Bin 44747 -> 0 bytes
 src/implementing_seaware_apps.md   |  28 +-
 src/infiniband_statements.md       |  36 +-
 src/kernel_policy_language.md      |  59 ++-
 src/libselinux_functions.md        |   4 +-
 src/lsm_selinux.md                 | 161 ++++---
 src/mac.md                         |   5 -
 src/mls_mcs.md                     |  45 +-
 src/mls_statements.md              |  84 ++--
 src/modes.md                       |   7 +-
 src/modular_policy_statements.md   |  28 +-
 src/network_statements.md          |  80 ++--
 src/network_support.md             |  78 ++--
 src/object_classes_permissions.md  | 255 +++++------
 src/objects.md                     |  40 +-
 src/pam_login.md                   |   7 +-
 src/policy_config_files.md         | 182 ++++----
 src/policy_config_statements.md    |  10 +-
 src/policy_languages.md            |   2 -
 src/policy_store_config_files.md   | 137 +++---
 src/policy_validation_example.md   |  14 +-
 src/polyinstantiation.md           |  31 +-
 src/postgresql.md                  | 145 +++----
 src/rbac.md                        |   9 +-
 src/reference_policy.md            | 321 ++++++--------
 src/role_statements.md             |  82 ++--
 src/seandroid.md                   |  91 ++--
 src/security_context.md            |  10 +-
 src/selinux_cmds.md                |   3 -
 src/selinux_overview.md            |   4 -
 src/sid_statement.md               |  24 +-
 src/styles_html.css                |  16 +-
 src/styles_pdf.css                 |  24 +-
 src/subjects.md                    |   7 +-
 src/terminology.md                 |   5 -
 src/title.md                       |  16 +-
 src/toc.md                         |   4 +-
 src/type_enforcement.md            |  55 ++-
 src/type_statements.md             | 672 ++++++++++++-----------------
 src/types_of_policy.md             |  31 +-
 src/user_statements.md             | 121 +++---
 src/users.md                       |  15 +-
 src/userspace_libraries.md         | 169 ++++----
 src/vm_support.md                  | 147 ++-----
 src/x_windows.md                   | 374 ++++++++--------
 src/xen_statements.md              | 370 ++++++----------
 src/xperm_rules.md                 | 146 +++----
 64 files changed, 2157 insertions(+), 2830 deletions(-)
 delete mode 100644 src/images/24-database-table.png

--
paul moore
www.paul-moore.com

Comments

Richard Haines Aug. 4, 2020, 10:31 a.m. UTC | #1
On Mon, 2020-08-03 at 21:33 -0400, Paul Moore wrote:
> This patchset helps to get us a little closer to finishing the work
> of converting The SELinux Notebook to markdown.  I believe this is
> a worthwhile goal for two main reasons: it makes the raw markdown
> much easier to read (the HTML tables are painful in source form),
> and it makes it easier to render the markdown into different formats
> (currently HTML and PDF).
> 
> My original goal for this patchset was to complete the markdown
> conversion before posting the series, but I now realize that was
> neither a practical or good idea.  While this patchset may miss my
> original goal, I do believe it is a step forward both in terms of the
> raw markdown and the rendered formats, and I would suggest we merge
> these changes assuming no strong objections.
> 
> For those who want to quickly check the markdown on GitHub or the
> rendered HTML and PDF formats, I've included the links below:
> 
> * https://drop.paul-moore.com/21.HGW6/SELinux_Notebook.pdf
> * https://drop.paul-moore.com/21.HGW6/SELinux_Notebook.html
> * 
> https://github.com/pcmoore/misc-selinux_notebook/tree/working-md_full
> 

I'm okay with these changes.

The changes of tables to lists in the policy rules files
(xperms_rules.md etc.)  makes the text much easier on the eye when
reading in all formats. Splitting the policy types looks better too.

I think a small number of the HTML tables will be difficult to convert
to pipe tables, also others when converted may require the HTML <br> to
make them more readable (using <br> seems to be the only way to get
line breaks in pipe tables). Still, see how it goes !!

Acked-by: Richard Haines <richard_c_haines@btinternet.com>

> ---
> 
> Paul Moore (16):
>       build: explicitly enable pandoc pipe_tables
>       css: identify table layout hacks
>       css: style improvements
>       x_windows: fully convert to markdown
>       xperm_rules: fully convert to markdown
>       xen_statements: fully convert to markdown
>       vm_support: fully convert to markdown
>       user_statements: fully convert to markdown
>       userspace_libraries: fully convert to markdown
>       type_statements: fully convert to markdown
>       all: remove all the <br> tags we haven't gotten to yet
>       all: unify example formatting (scripts, code, policy, etc) in
> markdown
>       all: don't use "`" for formatting text, use "*" instead
>       all: consolidate multiple blank lines into one
>       kernel_policy_language: convert the footnotes to markdown
>       title: assorted updates
> 
> Richard Haines (2):
>       postgresql: update PostgreSQL SELinux Support section
>       x_windows: don't call table 12 a table
> 
> 
>  src/apache_support.md              |  53 +--
>  src/auditing.md                    |  36 +-
>  src/avc_rules.md                   |  48 +--
>  src/bounds_rules.md                |  18 +-
>  src/cil_overview.md                |  43 +-
>  src/class_permission_statements.md |  44 +-
>  src/computing_access_decisions.md  |   2 -
>  src/computing_security_contexts.md | 224 +++++-----
>  src/conditional_statements.md      |  36 +-
>  src/configuration_files.md         |  10 +-
>  src/constraint_statements.md       |  52 +--
>  src/core_components.md             |  10 -
>  src/debug_policy_hints.md          |   5 -
>  src/default_rules.md               |  40 +-
>  src/domain_object_transitions.md   | 138 +++---
>  src/file_labeling_statements.md    |  58 ++-
>  src/global_config_files.md         |  16 +-
>  src/images/24-database-table.png   | Bin 44747 -> 0 bytes
>  src/implementing_seaware_apps.md   |  28 +-
>  src/infiniband_statements.md       |  36 +-
>  src/kernel_policy_language.md      |  59 ++-
>  src/libselinux_functions.md        |   4 +-
>  src/lsm_selinux.md                 | 161 ++++---
>  src/mac.md                         |   5 -
>  src/mls_mcs.md                     |  45 +-
>  src/mls_statements.md              |  84 ++--
>  src/modes.md                       |   7 +-
>  src/modular_policy_statements.md   |  28 +-
>  src/network_statements.md          |  80 ++--
>  src/network_support.md             |  78 ++--
>  src/object_classes_permissions.md  | 255 +++++------
>  src/objects.md                     |  40 +-
>  src/pam_login.md                   |   7 +-
>  src/policy_config_files.md         | 182 ++++----
>  src/policy_config_statements.md    |  10 +-
>  src/policy_languages.md            |   2 -
>  src/policy_store_config_files.md   | 137 +++---
>  src/policy_validation_example.md   |  14 +-
>  src/polyinstantiation.md           |  31 +-
>  src/postgresql.md                  | 145 +++----
>  src/rbac.md                        |   9 +-
>  src/reference_policy.md            | 321 ++++++--------
>  src/role_statements.md             |  82 ++--
>  src/seandroid.md                   |  91 ++--
>  src/security_context.md            |  10 +-
>  src/selinux_cmds.md                |   3 -
>  src/selinux_overview.md            |   4 -
>  src/sid_statement.md               |  24 +-
>  src/styles_html.css                |  16 +-
>  src/styles_pdf.css                 |  24 +-
>  src/subjects.md                    |   7 +-
>  src/terminology.md                 |   5 -
>  src/title.md                       |  16 +-
>  src/toc.md                         |   4 +-
>  src/type_enforcement.md            |  55 ++-
>  src/type_statements.md             | 672 ++++++++++++---------------
> --
>  src/types_of_policy.md             |  31 +-
>  src/user_statements.md             | 121 +++---
>  src/users.md                       |  15 +-
>  src/userspace_libraries.md         | 169 ++++----
>  src/vm_support.md                  | 147 ++-----
>  src/x_windows.md                   | 374 ++++++++--------
>  src/xen_statements.md              | 370 ++++++----------
>  src/xperm_rules.md                 | 146 +++----
>  64 files changed, 2157 insertions(+), 2830 deletions(-)
>  delete mode 100644 src/images/24-database-table.png
> 
> --
> paul moore
> www.paul-moore.com
Paul Moore Aug. 6, 2020, 1:58 a.m. UTC | #2
On Tue, Aug 4, 2020 at 6:31 AM Richard Haines
<richard_c_haines@btinternet.com> wrote:
> On Mon, 2020-08-03 at 21:33 -0400, Paul Moore wrote:
> > This patchset helps to get us a little closer to finishing the work
> > of converting The SELinux Notebook to markdown.  I believe this is
> > a worthwhile goal for two main reasons: it makes the raw markdown
> > much easier to read (the HTML tables are painful in source form),
> > and it makes it easier to render the markdown into different formats
> > (currently HTML and PDF).
> >
> > My original goal for this patchset was to complete the markdown
> > conversion before posting the series, but I now realize that was
> > neither a practical or good idea.  While this patchset may miss my
> > original goal, I do believe it is a step forward both in terms of the
> > raw markdown and the rendered formats, and I would suggest we merge
> > these changes assuming no strong objections.
> >
> > For those who want to quickly check the markdown on GitHub or the
> > rendered HTML and PDF formats, I've included the links below:
> >
> > * https://drop.paul-moore.com/21.HGW6/SELinux_Notebook.pdf
> > * https://drop.paul-moore.com/21.HGW6/SELinux_Notebook.html
> > *
> > https://github.com/pcmoore/misc-selinux_notebook/tree/working-md_full
> >
>
> I'm okay with these changes.
>
> The changes of tables to lists in the policy rules files
> (xperms_rules.md etc.)  makes the text much easier on the eye when
> reading in all formats. Splitting the policy types looks better too.

Thanks Richard.

> I think a small number of the HTML tables will be difficult to convert
> to pipe tables, also others when converted may require the HTML <br> to
> make them more readable (using <br> seems to be the only way to get
> line breaks in pipe tables). Still, see how it goes !!
>
> Acked-by: Richard Haines <richard_c_haines@btinternet.com>

Who doesn't love a good challenge :)

I went ahead and added your ACK to all the patches that weren't yours
(ACK'ing your own patch seems silly) and pushed the bunch to the repo
- thanks!