help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Matthew Singletary <matt.singletary@gmail.com>
Cc: discuss@mandoc.bsd.lv
Subject: Re: Mandoc for oil
Date: Sun, 16 Jun 2019 19:08:08 +0200	[thread overview]
Message-ID: <20190616170808.GD71520@athene.usta.de> (raw)
In-Reply-To: <CAAJ-tZJaRjB92YEAwCy0AANg9oi56hH=L6y195fnAafWjrCXPA@mail.gmail.com>

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.

 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

  reply	other threads:[~2019-06-16 17:08 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-06-14  8:16 Matthew Singletary
2019-06-14  8:43 ` Jan Stary
2019-06-14  8:54   ` Jan Stary
2019-06-14  9:24     ` Matthew Singletary
2019-06-14 11:40       ` Jan Stary
2019-06-14 12:29       ` Ingo Schwarze
2019-06-14 13:08         ` Jan Stary
2019-06-14 14:27         ` Jan Stary
2019-06-14 14:54           ` Ingo Schwarze
2019-06-16  2:39             ` Matthew Singletary
2019-06-16 17:08               ` Ingo Schwarze [this message]
2019-06-14  9:54 ` Stephen Gregoratto
2019-06-14 12:03   ` Jan Stary

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190616170808.GD71520@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mandoc.bsd.lv \
    --cc=matt.singletary@gmail.com \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).