From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 3d8e13a3 for ; Sun, 16 Jun 2019 12:08:12 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hcYdW-0006Xs-6U; Sun, 16 Jun 2019 19:08:11 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hcYdV-0007eQ-2o; Sun, 16 Jun 2019 19:08:09 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hcYdV-0004vN-0Z; Sun, 16 Jun 2019 19:08:09 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id e140fcaa; Sun, 16 Jun 2019 19:08:09 +0200 (CEST) Date: Sun, 16 Jun 2019 19:08:08 +0200 From: Ingo Schwarze To: Matthew Singletary Cc: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190616170808.GD71520@athene.usta.de> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> <20190614122941.GB25099@athene.usta.de> <20190614142714.GA34987@www.stare.cz> <20190614145415.GE25099@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.8.0 (2017-02-23) Hi Matthew, Matthew Singletary wrote on Sat, Jun 15, 2019 at 10:39:55PM -0400: > I've got a first attempt at an updated man page for osh (the pull > request is https://github.com/oilshell/oil/pull/337). I tried to find your draft of the manual page in there, but failed to find any substantial body of text - small surprise though, i consider the Github user interface totally unusable, so probably, i merely didn't find your text. > Any feedback would be appreciated. If you desire feedback on your draft, please simply post it here. > But while I can start copying from the markdown notes that are being > maintained by the main author, what's a normal/reasonable workflow for > updating man pages? Different projects have different policies for that. Personally, i recommend treating them exactly the same way as code: Commit changes to the -current branch whenever you find gaps or errors, then when a release comes, the newest version of the code and documentation will automatically gets released together. KISS. > For example, are there any recommended ways to generate/keep up to date > command line flags based upon source code, Absolutely not. It is utterly impossible to automatically generate documentation from source code, and any attempt at doing so is certain to result in documentation of abysmal quality. Not just for manual pages, for any kind of documentation. > or is the convention to handle those by hand? Yes, absolutely. When the code is changed, the developer changing the code should ask themselves: is this change visible to the end user, or is it purely internal? If it changes the user interface, they should figure out how the documentation needs to be updated. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv