From patchwork Wed Jun 24 08:07:30 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Sommerseth X-Patchwork-Id: 1163 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director7.mail.ord1d.rsapps.net ([172.31.255.6]) by backend30.mail.ord1d.rsapps.net with LMTP id 0Jy4NOKW817rPAAAIUCqbw for ; Wed, 24 Jun 2020 14:09:38 -0400 Received: from proxy14.mail.iad3b.rsapps.net ([172.31.255.6]) by director7.mail.ord1d.rsapps.net with LMTP id aGmJMeKW8169JwAAovjBpQ ; Wed, 24 Jun 2020 14:09:38 -0400 Received: from smtp22.gate.iad3b ([172.31.255.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy14.mail.iad3b.rsapps.net with LMTP id WBV2K+KW815SMQAA+7ETDg ; Wed, 24 Jun 2020 14:09:38 -0400 X-Spam-Threshold: 95 X-Spam-Score: 0 X-Spam-Flag: NO X-Virus-Scanned: OK X-Orig-To: openvpnslackdevel@openvpn.net X-Originating-Ip: [216.105.38.7] Authentication-Results: smtp22.gate.iad3b.rsapps.net; iprev=pass policy.iprev="216.105.38.7"; spf=pass smtp.mailfrom="openvpn-devel-bounces@lists.sourceforge.net" smtp.helo="lists.sourceforge.net"; dkim=fail (signature verification failed) header.d=sourceforge.net; dkim=fail (signature verification failed) header.d=sf.net; dmarc=fail (p=none; dis=none) header.from=openvpn.net X-Suspicious-Flag: YES X-Classification-ID: dd549dc0-b645-11ea-b209-52540041dff8-1-1 Received: from [216.105.38.7] ([216.105.38.7:34608] helo=lists.sourceforge.net) by smtp22.gate.iad3b.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id BF/29-02446-1E693FE5; Wed, 24 Jun 2020 14:09:38 -0400 Received: from [127.0.0.1] (helo=sfs-ml-1.v29.lw.sourceforge.com) by sfs-ml-1.v29.lw.sourceforge.com with esmtp (Exim 4.90_1) (envelope-from ) id 1jo9p5-0003ud-SR; Wed, 24 Jun 2020 18:08:35 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-1.v29.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jo9p4-0003uU-Rn for openvpn-devel@lists.sourceforge.net; Wed, 24 Jun 2020 18:08:34 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Content-Transfer-Encoding:MIME-Version:Message-Id: Date:Subject:To:From:Sender:Reply-To:Cc:Content-Type:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=DZKRIh6gqmo8l+PL0YBB+Y5j0Wvovcc2Gldwsk/nAAg=; b=ExqleaDPEjRpsiJwCMtHOqsB4N Ebm0bdKc+MLWjT59soahb3j7QMKEbtBAKn7uibVjfdDDdN9rQEnk6n7P2DLz5LTvipSP+jADZGfpL ysHPK825eQdL7kkCuj9fT3OL5qvpouraFV8YqpM6rZO6QCIR07h5Bz/c6NgP4WImMgxU=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Content-Transfer-Encoding:MIME-Version:Message-Id:Date:Subject:To:From: Sender:Reply-To:Cc:Content-Type:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To: References:List-Id:List-Help:List-Unsubscribe:List-Subscribe:List-Post: List-Owner:List-Archive; bh=DZKRIh6gqmo8l+PL0YBB+Y5j0Wvovcc2Gldwsk/nAAg=; b=V sgobEjeAF/Cq8W4GQYUsw1zLMaIyy3FkyV0Tdpo3ItIrNUYUP1Ugb/GQ6OJdodveB7fEoghTuKG/l /le0T7hgSWInfdkI5azr1hYclMn71TH8D50vl0U0MvnlVUzykwLKfRWhqp/iBBv4aF68+cgcLMO+H fWVvK0fWcpXd+3Oc=; Received: from mx0.basenordic.cloud ([185.212.44.139]) by sfi-mx-3.v28.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92.2) id 1jo9p2-00EF9k-4f for openvpn-devel@lists.sourceforge.net; Wed, 24 Jun 2020 18:08:34 +0000 Received: from localhost (unknown [IPv6:::1]) by mx0.basenordic.cloud (Postfix) with ESMTP id D833B837FE0 for ; Wed, 24 Jun 2020 18:08:13 +0000 (UTC) Received: from mx0.basenordic.cloud ([IPv6:::1]) by localhost (winterfell.topphemmelig.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id uCMWUiOAbUsk for ; Wed, 24 Jun 2020 20:08:07 +0200 (CEST) Received: from zimbra.sommerseth.email (zimbra.sommerseth.email [172.16.33.42]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx0.basenordic.cloud (Postfix) with ESMTPS id 8A1F48229D1 for ; Wed, 24 Jun 2020 20:08:07 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by zimbra.sommerseth.email (Postfix) with ESMTP id 160A34172FFF for ; Wed, 24 Jun 2020 20:08:06 +0200 (CEST) Received: from zimbra.sommerseth.email ([127.0.0.1]) by localhost (zimbra.sommerseth.email [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id 05cI7tISSRRM for ; Wed, 24 Jun 2020 20:08:05 +0200 (CEST) Received: from optimus.homebase.sommerseths.net (unknown [10.35.7.3]) by zimbra.sommerseth.email (Postfix) with ESMTPS id 1CCFA4172FFC for ; Wed, 24 Jun 2020 20:08:05 +0200 (CEST) From: David Sommerseth To: openvpn-devel@lists.sourceforge.net Date: Wed, 24 Jun 2020 20:07:30 +0200 Message-Id: <20200624180741.426-1-davids@openvpn.net> X-Mailer: git-send-email 2.26.0 MIME-Version: 1.0 X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. -0.0 SPF_HELO_PASS SPF: HELO matches SPF record 0.0 HEADER_FROM_DIFFERENT_DOMAINS From and EnvelopeFrom 2nd level mail domains are different -0.0 SPF_PASS SPF: sender matches SPF record X-Headers-End: 1jo9p2-00EF9k-4f Subject: [Openvpn-devel] [PATCH 00/11] man-page overhaul project X-BeenThere: openvpn-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox 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 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