"onf" <o...@disroot.org> writes:
i certainly agree that, for people not regularly creating new
man
pages from scratch, having to learn roff and a macro library
probably feels like unnecessary work.
I had mostly based this on the original quotation of Andrew
Gallant,
but personally it took me a while just to get acquainted with
the
general syntax of troff, understanding how macros and escapes
work,
etc., even before I learned any macros. So no, I think it
applies
generally.
Sorry, i'm not sure what you're saying "no" to here? i wrote:
having to learn roff and a macro library
where "learn roff" to me includes "the general syntax of troff,
understanding how macros and escapes work".
While you can absolutely get a list of manpages containing a
specific
term of a specific type with apropos (like the example you
gave), what
I was getting at is that you can't say to your pager "jump to
the flag
-e". The best you can do is `/^ +-e`. I feel like if such
features were
in place, there would be much bigger incentive to write manpages
by
hand.
Well, what i was trying (poorly!) to get at is that if you've got
semantic markup rather than presentational markup, one can use
that fact for the sort of functionality you describe: a program
could find the documentation for that flag by searching the source
for '.Op Fl e', which would be more reliable than having to make
guesses / use heuristics.
With as things are right now, there is very little difference
between
man and mdoc from the user's perspective (outside of mdoc's
consistent
formatting, but I doubt many people notice that). And as a
result it
doesn't really matter if you write your manpage by hand or
generate it
(with something at least a bit capable, i.e. not from plain
markdown)
because the end result is fairly similar.
Indeed, right now, there isn't much difference from the end-user's
perspective. But i feel that the use semantic markup would
significantly facilitate the development of functionality,
including in man page viewers, that end-users _would_ notice
(which i feel the 'apropos' example i provided gives something of
a taste of).
I don't know either of those macro packages well
Fair enough. :-) i'm pretty familiar with at least the core of
mdoc(7) as a result of my porting; a quick and very unscientific
analysis of my *-man-page repos
(cf. https://wiki.gentoo.org/wiki/User:Flexibeast#The_s6_ecosystem
) suggests i've added around 20 000 macros during several dozen
hours of work creating those ports. Although i admit my earlier
ports, such as s6-man-pages, probably need a full review of their
macro usages, given that i was still in the early stages of
learning mdoc at the time.
but the equivalent
of man's SH seems to be Sh in mdoc. (I might have confused you
by
calling them subheadings when they are in fact section
headings.)
Ah, yeah, section headings are indeed Sh; and i certainly use all
caps for section headings, because that's the convention.
I feel like ideally, though, the authors should write sentence
case
and the macros should take care of capitalization if it's
desirable
(with .stringup or similar)... Clearly mdoc's semantic approach
has
its limits :)
To me, one of the main points of separating semantics from
presentation - particularly as we've learned through the
experience of the Web - is to facilitate end-users having some
control over how the content is presented to them, because there
isn't always a single form of presentation that meets all the
needs of every person. Whilst there might be typographic rules
that are widely agreed upon, there are also things that are very
much subjective and user-specific, and as such, i strongly feel
that certain forms of presentation shouldn't be forced on the
user.
For example: i struggle with text on a black background, and thus
strongly prefer 'light' themes - including in my full-screen
terminal, which is black-on-white. Yes, even at night. :-P But
there are people for whom this is anathema, and who instead want
black backgrounds - possibly with some low-contrast foreground
colour, such as dark blue. But this combination is unreadable to
me. (i myself grew up with phosphorescent green-on-black CRT
monitors in the early 80s, which i'm glad i no longer have to deal
with.)
To try to demystify it for others, i wrote this quickstart
guide:
https://github.com/flexibeast/guides/blob/master/mdoc-quickstart.md
Cool, that's a really nice tutorial! I will try to give some
constructive suggestions/criticism...
Thank you! Most of these i'll take on board. :-) As a general
point - the guide is intended to be merely be an _introduction_ to
mdoc, to give people some sense of how it works; it's certainly
not intended to be a general text for writing man pages with
mdoc. But the document doesn't actually say this, so i'll add a
note to this effect.
If this is really intended for the absolute beginner who doesn't
understand roff, I would suggest properly explaining what roff
macros
mean before using that term. You use them in Introduction
without any
explanation, then explain it slightly in the Background section
only to
dive into the issues with man and the benefits of mdoc without
their
meaning having been adequately explained. I suggest something
along the
lines of:
roff is a typesetting language ultimately descended from
RUNOFF,
the first computer typesetting system. In roff, formatting is
carried out by the means of so-called requests (formatting
commands). To simplify repetitive formatting tasks, requests
can be grouped into macros which perform a particular function
(such as format its arguments as a heading). A collection of
macros which all serve a shared purpose (such as formatting a
letter) is called a macro package.
Traditionally, the man(7) macro package has been used to
format
manpages. ...
Yep, good point, i'll work on this.
You say that BSD mandoc provides a roff implementation, but
afaik it
implements only as much roff as is necessary to format
manpages.[1]
I realize it's difficult to succinctly describe what exactly BSD
mandoc is, though.
Indeed, good point.
When mentioning the use of \& to disable the meaning of . at the
beginning of line, ' (no-break control character) also needs to
be
mentioned, which is much more common at the beginning of a line.
Okay, i'll add that in.
When discussing the Op and Fl macros, the way macro names in
arguments
are handled by mdoc should be explained, because the fact you
call Fl
a macro and it appears only as a text argument to Op is
confusing.
(I know Fl IS a macro, but it's used like a text argument in the
code.)
The part discussing the It macro makes this feel even more
confusing as
you write:
The It macro is a list Item. It's parsed, so we use the Fl
macro as
its argument, with a literal as the argument to the Fl macro.
but just before that you said:
Note that any formatting command is on a distinct line of its
own,
rather than being inline.
Agreed; i'll try to address this.
You also write that:
The -tag argument specifies that item bodies should be
indented by
the value of the -width argument.
but from reading mdoc(7), it seems to me the line:
.Bl -tag -width x
actually indents by the width of character x, not its numeric
value.
Correct, indeed. What i wrote was ambiguous; i was trying to say
"the width of the value provided to `-width`". Your reading seems
to me to be the one people are more likely to make, so i'll fix
this.
When you write:
Note that a new sentence starts on a new line. To start a new
paragraph, use the Pp macro.
I would suggest adding that beginning a sentence on a new line
is
merely a matter of style, not a requirement of the language.[2]
Fair.
When you write an example exit status section, I would expect to
hear
about the Ex macro, which is often preferable to writing it by
hand.
The 'Ex' macro you're referring to here is man(7)-specific; the
'Ex' macro in mdoc(7) is for exit status.
And by the way, there is technically no such thing as exit
status -1,
it becomes 255.[3]
Yes, but this document is about mdoc(7), not about the specifics
of exit statuses, so i'll just remove the second sentence.
Missing word:
Man pages referenced in this section should [be] sorted by
section
number
👍
When you write:
Note how the commas are a distinct final argument on the
request
lines; this allows the punctuation to be handled
appropriately.
I suggest adding something like this at the end:
(i.e. being put right after the closing parentheses without
any space
between them).
Sure.
When you write:
Note that we made no roff requests directly; only roff macros
were
used.
I feel like s/roff/mdoc/2 would convey the meaning better.
Yeah, fair enough.
I can also imagine that a section about tbl would come in handy.
In a complete guide to writing man pages with mdoc,
definitely. :-) But yeah, as i wrote above, i'm just trying to
give people the flavour of writing man pages with mdoc, hopefully
convincing them that it's not as scary and difficult as they might
have thought. :-)
Thanks for the feedback!
Alexis.
