Skip to content

man-page overhaul project

David Sommerseth openvpn-devel 1 version In review

Get series with b4
b4 am [email protected]...

Versions newest first

  1. v1 Latest10 of 11 patches 1 replyIn review

10 of 11 patches are in this archive. The cover letter announces 11.

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/11doc/man: Add an .rst formatted version of the man pagedoc/openvpn.8.rst+5882 -00 replies
2/11doc/man: Replace old man page with generated man page.gitignore INSTALL configure.ac +3 more+61 -76460 replies
3/11doc/man: Move <connection> profiles sectiondoc/openvpn.8.rst+78 -710 replies
4/11doc/man: Remove unsupported options in OpenVPN 2.5doc/openvpn.8.rst doc/unsupported-options.rst+35 -1420 replies
6/11doc/man: Move --bind from generic to link sectiondoc/man-sections/generic-options.rst doc/man-sections/link-options.rst+7 -70 replies
7/11doc/man: Move --dhcp-option from client to vpn-network sectiondoc/man-sections/client-options.rst doc/man-sections/vpn-network-options.rst+69 -690 replies
8/11doc/man: Mark compression options as deprecateddoc/man-sections/protocol-options.rst+10 -90 replies
9/11doc/man: Move some options from link to advanced sectiondoc/man-sections/advanced-options.rst doc/man-sections/link-options.rst+40 -400 replies
10/11doc/man: Moved --reneg-* options to its own sectiondoc/man-sections/encryption-options.rst doc/man-sections/link-options.rst doc/man-sections/renegotiation.rst+54 -470 replies
11/11doc/man: Cleaned up the examplesdoc/man-sections/examples.rst+11 -940 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

Cover letter [Openvpn-devel] [PATCH 00/11] man-page overhaul project

Hi,

This is the first real review round of the man-page overhaul project. Since the n/groff based openvpn.8 format is fairly cumbersome to edit, we agreed at the 2019 Hackathon in Trento to move the man page into something more editing and management friendly.

This set of patches converts the openvpn.8 file into the ReStructuredText format (.rst) which can easily be converted into both man and html files using python-docutils. The advantage of this format is that it is easy to edit in any plain text editors and displays reasonably well in any terminals. And it will be easier to review patches man page updates sent to the mailing list.

To avoid everyone building the OpenVPN source tarball to have the full python stack available, the doc/Makefile.am file has been adopted to generate the man and html files when we create the source tarball we distribute in releases. Only users only pulling down the source directly from git will need to have python-docutils available.

As I worked my way through the man page, there were several things which was less good. Lots of options where misplaced in not related sections, a few options where documented several places. And lots of the sections overlapped quite a bit. From patch 5/11 splits the whole man page into several smaller files; one file per section. This is all tied into a single man-page/html file when running the rst2man/rst2html tools. The following patches just cleans up and moves some options into more suitable sections.

I will continue to update my own git branch containing this work as review comments come in until this is merged into master. You can find it here:

https://gitlab.com/dazo/openvpn/-/tree/dev/man-reformatting/doc

kind regards,

David Sommerseth
OpenVPN Inc.

David Sommerseth (11):
doc/man: Add an .rst formatted version of the man page doc/man: Replace old man page with generated man page doc/man: Move <connection> profiles section
doc/man: Remove unsupported options in OpenVPN 2.5 doc/man: Split up and reorganize main man page doc/man: Move --bind from generic to link section doc/man: Move --dhcp-option from client to vpn-network section doc/man: Mark compression options as deprecated doc/man: Move some options from link to advanced section doc/man: Moved --reneg-* options to its own section doc/man: Cleaned up the examples

 .gitignore                               |    1 +
 INSTALL                                  |    3 +-
 configure.ac                             |   15 +-
 doc/Makefile.am                          |   56 +-
 doc/README.man                           |   23 +
 doc/man-sections/advanced-options.rst    |  107 +
 doc/man-sections/client-options.rst      |  355 +
 doc/man-sections/connection-profiles.rst |   75 +
 doc/man-sections/encryption-options.rst  |  136 +
 doc/man-sections/examples.rst            |  241 +
 doc/man-sections/generic-options.rst     |  436 ++
 doc/man-sections/inline-files.rst        |   25 +
 doc/man-sections/link-options.rst        |  410 ++
 doc/man-sections/log-options.rst         |   74 +
 doc/man-sections/management-options.rst  |  136 +
 doc/man-sections/network-config.rst      |    9 +
 doc/man-sections/pkcs11-options.rst      |   81 +
 doc/man-sections/plugin-options.rst      |   52 +
 doc/man-sections/protocol-options.rst    |  228 +
 doc/man-sections/proxy-options.rst       |   66 +
 doc/man-sections/renegotiation.rst       |   53 +
 doc/man-sections/script-options.rst      |  807 +++
 doc/man-sections/server-options.rst      |  769 +++
 doc/man-sections/signals.rst             |   30 +
 doc/man-sections/tls-options.rst         |  643 ++
 doc/man-sections/unsupported-options.rst |   33 +
 doc/man-sections/vpn-network-options.rst |  531 ++
 doc/man-sections/windows-options.rst     |  245 +
 doc/openvpn.8                            | 7631 ----------------------
 doc/openvpn.8.rst                        |  169 +
 30 files changed, 5794 insertions(+), 7646 deletions(-)
 create mode 100644 doc/README.man
 create mode 100644 doc/man-sections/advanced-options.rst
 create mode 100644 doc/man-sections/client-options.rst
 create mode 100644 doc/man-sections/connection-profiles.rst
 create mode 100644 doc/man-sections/encryption-options.rst
 create mode 100644 doc/man-sections/examples.rst
 create mode 100644 doc/man-sections/generic-options.rst
 create mode 100644 doc/man-sections/inline-files.rst
 create mode 100644 doc/man-sections/link-options.rst
 create mode 100644 doc/man-sections/log-options.rst
 create mode 100644 doc/man-sections/management-options.rst
 create mode 100644 doc/man-sections/network-config.rst
 create mode 100644 doc/man-sections/pkcs11-options.rst
 create mode 100644 doc/man-sections/plugin-options.rst
 create mode 100644 doc/man-sections/protocol-options.rst
 create mode 100644 doc/man-sections/proxy-options.rst
 create mode 100644 doc/man-sections/renegotiation.rst
 create mode 100644 doc/man-sections/script-options.rst
 create mode 100644 doc/man-sections/server-options.rst
 create mode 100644 doc/man-sections/signals.rst
 create mode 100644 doc/man-sections/tls-options.rst
 create mode 100644 doc/man-sections/unsupported-options.rst
 create mode 100644 doc/man-sections/vpn-network-options.rst
 create mode 100644 doc/man-sections/windows-options.rst
 delete mode 100644 doc/openvpn.8
 create mode 100644 doc/openvpn.8.rst
Signature · 1 line
2.26.0