| Message ID | 20200624180741.426-1-davids@openvpn.net |
|---|---|
| Headers | show |
| Series | man-page overhaul project | expand |
On 24/06/2020 20:07, David Sommerseth wrote: > 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 > So sf.net mailing list is grumpy at me for sending a large mail, patch 5/11 is currently waiting to be unlocked by the list admin. In the mean time, here's the patch: <https://gitlab.com/dazo/openvpn/-/commit/6eef9d3b1989166542805644cbc74baa96c72a80.patch>