Hello Ingo,
On Fri Jan 24, 2025 at 7:51 PM CET, Ingo Schwarze wrote:
> onf wrote on Fri, Jan 24, 2025 at 12:59:03PM +0100:
> > On Fri Jan 24, 2025 at 4:15 AM CET, Alexis wrote:
>
> >> (My first port was of the documentation for the s6 package, and
> >> unfortunately, my learning-on-the-fly shows. Ingo has kindly given
> >> me good feedback regarding this, but many of his
> >> suggestions/recommendations are not yet implemented, due to lack
> >> of Tuits - assistance with improvements would certainly be
> >> welcome.)
>
> > Would you mind sharing some of that feedback, if it can be generalized?
> > I am currently working on mdoc documentation for neatroff, so any advice
> > not already contained in mandoc's mdoc(7) would be appreciated!
>
> While parts of it may be a bit dusty and i might have to check whether
> a few things could become even better by providing more stringent or
> more relaxed advice as experience accumulated, this is still a good
> resource for people having throughly digested mdoc(7) and taking the
> extended documentation with minor grains of salt:
>
> https://mandoc.bsd.lv/mdoc/
>
> In particular, do not miss the Appendix, which is actively maintained.
Thank you for the pointers; the Appendix in particular is quite useful.
However, there are some things which I haven't found in there.
Perhaps they would make good additions.
1. Escape sequences in the sense of inline commands, i.e. how to mark
up syntax like \f[font]? Does it fit under Cm?
2. stdin, stdout, stderr without the /dev/; do those fit under Pa?
Practice among mdoc documents seems inconsistent.[1]
3. Displaying " as a literal character. Sq is suggested for displaying
single characters, but it seems to be a poor match for ". I am
currently using Sy.
By the way, the entry for emphasis says 'stess' instead of 'stress'.
Also, http://manpages.bsd.lv/mdoc.html says:
To display output, you must invoke nroff as nroff -mandoc file.
The mandoc flag indicates that input is in mdoc.
That's wrong on several levels, but since this is meant to be a tutorial
and some level of simplification is necessary, s/man/m/g seems like the
easiest way to make it acceptable.
~ onf
[1] Querying mdoc manuals installed on my machine:
bsdtar(1): stdout without markup
bsdunzip(1): Va stderr, stdout without markup
sndioctl(1): Em stdout
ssh-agent(1): Dv stdout
sshd_config(5): Xr stdout 4, Xr stderr 4
