"onf" <o...@disroot.org> writes:
I was reacting to the first sentence, which you've left out
above.
My comprehension of it was that when I say it takes several
hours,
I must mean man rather than mdoc, to which I was saying: no, it
takes a while with both packages. I might have misunderstood
you,
though.
Oh, i see. No, all i was trying to do was confirm that you'd been
working with man(7), not mdoc(7) (because most of the time, when i
encounter people complaining about the challenges of writing man
pages, they are indeed using man(7)). i wasn't trying to imply
anything other than that, and certainly not wanting/trying to
imply that it's _only_ man(7) that takes several hours to learn.
Agreed. I was mostly complaining such a thing hasn't been done
yet
despite mdoc existing since the 90s (iirc). I'm afraid the
approach
you describe likely wouldn't be sufficient, though, because
there is
little correspondence between source line numbers and output
line
numbers.
No indeed. i was thinking that the viewer program can maintain an
internal table of where certain things occurred in what was
output, à la overlays in Emacs. But this was just off the top of
my head, and i acknowledge this might be unworkable for some
reason.
Such a thing would have to be somehow integrated with
mandoc/troff
itself. The simplest solution I can think of is mdoc inserting the
ECMA-48 Privacy Message escape sequence[1], which allows the
insertion
of hidden text into the output (all terminal emulators ignore it,
afaik), after each formatting element with terminal output.
.... and this might be the actual approach required.
I would agree if there wasn't several decades of mdoc usage on
the
BSD side without the development of such features.
Fair point.
I agree wholeheartedly, which is exactly why I suggested that Sh
arguments are entered in sentence case and uppercased only if
that's desired.
*nod*
Dark blue on black background IS undreadable. The standard
terminal
color combination is light gray on black. I myself use white on
black and low screen brightness.
Okay. But light grey on black is _also_ quite difficult for me to
read. It might have been less so when i was younger; i'm not
sure. But certainly as i've gotten older, my eyesight has changed
in ways that has made _any_ dark themes more and more difficult to
deal with.
The particular bee i have in my bonnet, in this context, is my
overall experience of the 'dark theme' crowd. i've regularly see
outrage when a dark-theme-preferrer is presented with something
with what's effectively a light theme, and an expectation that a
dark theme will be provided as an alternative, but i've seen
little evidence of dark-theme-preferrers seeking to provide a
light theme for when the situation is reversed - with the overall
effect being "dark themes are objectively better for everyone, you
just have poor taste or don't know what you _really_ need".
Just to be clear: i'm in no way intending to imply that this is
where you're coming from, as i certainly didn't get any such
impression from anything you've written.
I understood it's more of an introductory text rather than a
full
reference, I guess I just didn't get it's meant more as a
"teaser"
(for a lack of better word) than a full introduction.
I guess my personal approach to introductions is closer to
"reference of the essentials that assumes little prior
knowledge",
which is why I suggested the addition of tbl. So fair enough.
'Teaser' is also a reasonable word. Of course, i didn't use the
word 'introduction' in the title; the phrase i actually used in
the title is "a quickstart guide", which to me suggests "getting
you started [with the basics]". But still, i appreciate knowing
the impression that the document gave you, and yeah, i'll make the
changes i mentioned in my previous email.
I was in fact referring to mdoc's Ex macro. To quote mdoc(7):
Ex -std [utility ...]
Wow, i don't know how i managed to misread what you wrote! For
some reason, i had read you as talking about using the man(7) EX
macro, even though you clearly did no such thing. Sorry! %-}
Yes, but this document is about mdoc(7), not about the
specifics
of exit statuses, so i'll just remove the second sentence.
I know it's not about exit statuses. What I was trying to say is
that if such a sentence appeared in an actual manpage, it would
be
technically incorrect, because a program cannot return -1 on
Unix,
so it shouldn't appear in an example of how to write a manpage
either.
Sure; as i said, i'll remove that text. When i was putting that
piece together, i was primarily focused on trying to demonstrate
how mdoc(7) _macros_ are used to write man pages, not "this is how
to write a man page in general, using mdoc(7)". Yet the title i
used for the document was "Writing man pages with mdoc(7)". :-P So
i need to change that title, and perhaps i should just use lorem
ipsum in the contents of the example man page ....
Alexis.
