Follow-up Comment #11, bug #67881 (group groff):
Notes from my working copy...
[comment #7 comment #7:]
> 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.
I've taken care of it. Resolved the merge conflict from your quickie. :)
> 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.
Fair. I'm adding a brief new paragraph early in _groff_'s _roff_(7) (the
"Concepts" section) to address it. It's a necessary point of divergence from
the section's basis in our Texinfo manual, which is more conversational.
> * 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,
I was about to point this out.
> 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.
Hmm, I'll see if I can add a characterization of the _groff_char_(7) page's
purpose to that previous paragraph to clue in the reader. It doesn't make
sense to me to cite it _again_ so immediately.
> * 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.
Yeah, as noted, saying "U+002D" will clear things up perfectly for those who
care to know.
> * 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.
I'm deferring this work. I haven't even gotten through my _first_ pass of
this man page yet. (My wheels fell off around...
...yup, "Introduction to manual and general text domains", it looks like.
While its organization might leave something to be desired, I do like the fact
that _groff_mdoc_(7) exercises practically every macro it documents--the
exception being the truckload of enclosure/quoting macros, which I think got
us into trouble at some point, but I don't see a Fixed Savannah ticket about
the incident. Oh well.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?67881>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
