Follow-up Comment #11, bug#59962 (group groff): Thanks to Dave for covering some of these points. That may help make my reply shorter (but don't count on it đ ).
[comment #8 comment #8:] > I think we discussed this already, I sill think this is not correct, but it does not make sense to discuss this further I would just point out (as I learned from Ingo Schwarze) that mixed-case section and subsection headings are better for accessibility purposes. Apparently, screen readers pronounce sequences of capitals letter-by-letter, not as words. > #2 > Thanks for the explanation. > a) consistency is key (and also for tools processing the man pages), so for me youngster (I only started Linux/Unix mid 90s) putting references in bold is all I know, hence I ask to make it consistent when I see a deviation. > > And at least some tools (external to roff) "know" these rules and hyperlink (e.g. in HTML) B<foo>(x). > > The new macro is a great idea and I agree that it will be picked up properly very slowly. Is it a GNU extension and which minimum requirement is attached to it? It would be great if there is a web page explaining the use of this (and the minimum requirements as well) so I could point people to this. I expect people to tell me "my software runs on xyz" so I cannot use it or "I support this old Linux distribution(s)". As Dave said, [https://github.com/9fans/plan9port _plan9port_] and _groff_ 1.23.0, released in July, support it. [https://cvsweb.bsd.lv/mandoc/man_html.c?rev=1.187&content-type=text/x-cvsweb-markup&sortby=date Likely the next release of _mandoc_ will.] Here's what _groff_man_(7) says nowadays: .MR topic manualâsection [trailingâtext] (since groff 1.23) Set a man page cross reference as âtopic(manualâsection)â. If trailingâtext (typically punctuation) is specified, it follows the closing parenthesis without intervening space. Hyphenation is disabled while the cross reference is set. topic is set in the font specified by the MF string. The cross reference hyperlinks to a URI of the form âman:topic(manualâsection)â. > And yes, the probably best thing would be to request all those markup languages with converters into *roff to use this macro during conversion, this would probably speed up the conversion quite a bit. I don't _expect_ any converters to start taking it up until some readers of man pages see the macro in the wild and wonder why their converters aren't producing it. And it is probably easier for the users of such converters to convince their maintainers to adopt the new macro than for me to approach them singing the praises of my own invention. (I use the term "invention" with some reluctance. Ingo says that `MR` "copies" _mdoc_(7)'s `Xr`, but as far as I can tell, both have a common ancestor [or at least an analogue] in the `MS` macro of DEC Ultrix _man_(7), which _groff_ has documented for decades.) > To be honest, I know very little about *roff myself, so if I were to write a man page, I would use some higher level tool myself, in the distant past I used SGML. In my opinion it is not difficult, and I have spent many hours revising _groff_man_(7) and _groff_man_style_(7) trying to make the subject approachable. > b) The "bold is literal and italic is variable" is very helpful to me both as reader and as a translator. I'm glad to hear it. It's a good rule of thumb, but please don't over-apply this principle. As _groff_man_style_(7) says: Use bold for literal portions of syntax synopses, for commandâline options in running text, and for literals that are major topics of the subject under discussion; for example, this page uses bold for macro, string, and register names. In an .EX/.EE example of interactive I/O (such as a shell session), set only user input in bold. [...] Use italics for file and path names, for environment variables, for C data types, for enumeration or preprocessor constants in C, for variant (userâreplaceable) portions of syntax synopses, for the first occurrence (only) of a technical concept being introduced, for names of journals and of literary works longer than an article, and anywhere a parameter requiring replacement by the user is encountered. An exception involves variant text in a context already typeset in italics, such as file or path names with replaceable components; in such cases, follow the convention of mathematical typography: set the file or path name in italics as usual but use roman for the variant part (see .IR and .RI below), and italics again in running roman text when referring to the variant material. [...] Observe what is not prescribed for setting in bold or italics above: elements of âsynopsis languageâ such as ellipses and brackets around options; proper names and adjectives; titles of anything other than major works of literature; identifiers for standards documents or technical reports such as CSTR #54, RFC 1918, Unicode 13.0, or POSIX.1â2017; acronyms; and occurrences after the first of a technical term. Be frugal with italics for emphasis, and particularly with bold. Article titles and brief runs of literal text, such as references to individual characters or short strings, including section and subsection headings of man pages, are suitable objects for quotation; see the \(lq, \(rq, \(oq, and \(cq escape sequences in subsection âPortabilityâ below. > Sometimes the text is very hard to read, and having an indication what is the actual variable really helps, especially if I have little knowledge of the topic. And in *many* man pages this is done, so consistency is key again. Agreed. > Ideally we had semantic markup, hard coding "bold", "italic" etc. so semantics is not nice. I agree. [https://lists.gnu.org/archive/html/groff/2022-12/msg00078.html I have an idea for further reforming _man_(7) along these lines.] (Full disclosure: in the year since I posted that, I have come to think that it would be better to make the "tag" macro an enclosing pair. This (1) more closely resembles the block-structured nature of HTML and other modern formatting/markup systems and (2) safely leaves the macros ignorable by systems that don't know about (or reject) them, preserving the _textual_ content of the page. As a straw-man example just to make this concrete... .DC filename I \" set anything with tag "filename" in font I (italics) Blah blah blah then open the file .HS filename .I /etc/passwd .HE to see the list of users with accounts on your system (assuming you're not using LDAP or something like that). (_groff man_'s font macros would need to be updated to suppress their own changes of font to honor that imposed by the "tag class", when one applies. There is the question of what to do about trailing punctuation (not necessarily punctuation--it could be anything), as with calls like ".IR /etc/passwd ." This will require some thought. And re-implementing _mdoc_ is an anti-goal.) > #5 > The current state in my VT is that the arrows work (jay!), the only have a box before/above which is rendered as straight line in an xterm (vertically or horizontally). So from my point this is very, very minor and not a problem of *roff. It sounds like the VT font is missing mappings for the ACS "HLINE" and "VLINE" symbols. This should be fixable with an update to the "acsc" _terminfo_ capability code for your terminal type. It can be made to fall back to ASCII characters for those specific characters. Further, you can supply your own _terminfo_ definition for your terminal type in $HOME, and not have to alter any packages supplied by your distributor. What terminal type are you using? In other words, what does "echo $TERM" say on your Linux VT? > And as usual, thanks for your very helpful and extensive explanations. My pleasure. If I leave anything vague--or if I am incorrect!--please raise the point and I will attempt to remedy it. This has been quite the discussion. What remains for resolution of this ticket? Regards, Branden _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?59962> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
