Page MenuHome GnuPG

doc: U+2010 HYPHEN vs. U+002D HYPHEN-MINUS for man pages
Testing, WishlistPublic

Description

If it were written for man-only, we should distinguish character usage of U+2010 and U+002D.
We maintain the documents in Texinfo as source format and generate man pages by yat2man.
In this situation, I'm not sure how to handle the problem reported for our man pages:

https://bugs.debian.org/1050042
https://bugs.debian.org/1041731

Possibly, we somehow put a workaround into yat2man.

Event Timeline

gniibe triaged this task as Wishlist priority.Aug 22 2023, 3:32 AM
gniibe created this task.

Ideally, we should change the source document to use @minus{} for a minus sign, and keep - only when it means a hyphen. But we cannot do that blindly; We need to handle it with care, in a way of case by case (Texinfo manual suggests no use of @minus{} with @code or @example, but it is needed for groff man pages in many cases).... We would need to consider each occurrence of - in our document. That's too much (if it were me to fix).

My workaround (not perfect) would be modification of yat2man like following:

diff --git a/doc/yat2m.c b/doc/yat2m.c
index c2806e3..9d94bd9 100644
--- a/doc/yat2m.c
+++ b/doc/yat2m.c
@@ -775,8 +775,11 @@ write_th (FILE *fp)
 
     }
   else
-    fprintf (fp, ".TH %s %s %s \"%s\" \"%s\"\n",
-             name, p, isodatestring (), opt_release, opt_source);
+    {
+      fputs (".char - \\-\n", fp);
+      fprintf (fp, ".TH %s %s %s \"%s\" \"%s\"\n",
+               name, p, isodatestring (), opt_release, opt_source);
+    }
 
   free (name);
   return 0;

That is, to treat - in the source as minus sign for man pages.
This may be wrong for perfectionist, but it's backward compatible.

gniibe mentioned this in Unknown Object (Event).Aug 28 2023, 6:40 AM

I guess we should follow the GNU standards and provide only info files ;-)

Possible approach for source texinfo files and yat2m would be:

  • For the use case of an explanation of option where we do something like @item --s2k-count @var{n}, do: @item @option{--s2k-count} @var{n}
    • That is, explicitly use @option for option
    • This practice allows use of hyphen with @item
  • Every occurrence of command in the source (e.g., gpg-agent) should be quoted by @command {e.g., @command{gpg-agent}), or else, cut&paste for the command name won't work (as it may be hyphen of U+2010).
  • Fix yat2m to generate \- for the character - in @code, @example, @command, and @option

I learned about how @item is handled by TeX. By @table command, user specifies how to handle the item line. In the case of GnuPG, it is like:

@table @gnupgtabopt
@item --version
...
@item --help

(Emacs uses @table @samp, while GCC uses @table @gcctabopt.)
And @gnupgtabopt is a macro which is expanded to @code{\body\}

So, explicitly using @option in the item line is wrong.
We should parse the item line and if it's something like @samp, @code, @option, or @...tabopt, it is handled just as @samp, @code, and @...tabopt.

To do this correctly, we need to have a stack of table specification.

gniibe changed the task status from Open to Testing.Nov 15 2023, 6:40 AM
gniibe claimed this task.

@item handling with @table has been pushed.