Update of bug #67881 (group groff):
Assigned to: schwarze => gbranden
Planned Release: None => 1.24.0
_______________________________________________________
Follow-up Comment #7:
Hi Branden,
[comment #6 comment #6:]
> Ingo, did you mean to reopen this?
No, i did not intend to reopen this, sorry about that, and i'm not completely
sure how that happened - maybe because i started writing the comment before
you resolved the ticket but didn't finish it until after you resolved it, so
maybe Savannah reverted part of your changes including the status. It's a bit
of a pain that even when using the "Preview" button, Savannah does not tell
the user which changes the "Submit" button will subsequently commit.
The main purpose of the comment was to ask whether the two mandoc pages need
an update.
> What would you like to see done, or what defect do you perceive in Git HEAD?
One grammatical mistake is obvious:
As a typesetting system,
.Xr roff
distinguishes hyphens,
minus signs,
-and various sorts of dash.
+and various sorts of dashes.
Feel free to commit that yourself or tell me to.
The new text is not particularly clear in a number of respects:
* Unlike the mdoc(7) page from mandoc, groff_mdoc(7) never properly introduces
the concept of escape sequences, even though it talks about escape sequences
in various places. For comparison, mdoc(7) says up front:
Many aspects of the basic syntax of the mdoc language are based on the
roff(7) language; see the LANGUAGE SYNTAX and MACRO SYNTAX sections in
the roff(7) manual for details, in particular regarding comments, escape
sequences, whitespace, and quoting. However, using roff(7) requests in
mdoc documents is discouraged; mandoc(1) supports some of them merely
for
backward compatibility.
* The phrase "roff distinguishes hyphens, minus signs, and various sorts of
dashes" is less helpful than it could be because it fails to say how it
distinguishes those; pointing to groff_char(7) would be helpful, even though
unlike mandoc_char(7), groff_char(7) lacks a section "Dashes and Hyphens" and
the related information appears scattered around various places.
* Admittedly, there is a pointer to groff_char(7) in the preceding paragraph,
but that paragraph appears to be unrelated (and it appears in a place that
puts way too much emphasis on it - \( and \*( are quite arcane technicalities
of minimal importance that are not well-placed above all the important stuff),
so users will likely not understand that's the place to learn how to
distinguish hyphens and dashes, unless they already know.
* The wording seems both more cumbersome and less clear than it could be. It
is not made explicit what "hyphen-minus" refers to (the ASCII and Unicode code
point name) and it is unclear what the point of copy-and-paste is unless you
unambiguously and explicitly say what the intended output glyph is. This
could be made clearer by talking about 'an ASCII 0x2d “hyphen-minus”
output glyph' (as in mandoc_char(7)), or a similar wording. For example, the
wording "U+002d" could be used if you prefer talking about Unicode to talking
about ASCII.
* Several of the section titles in groff_mdoc(7) are not descriptive: what is
the difference between "Description", "Getting started", "Usage", and "Other
possible pitfalls"? This could use some sorting, i guess.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?67881>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
