From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.2 Received: (qmail 27057 invoked from network); 27 Apr 2020 00:16:51 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with UTF8ESMTPZ; 27 Apr 2020 00:16:51 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 00816efe for ; Sun, 26 Apr 2020 19:16:48 -0500 (EST) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 054e2451 for ; Sun, 26 Apr 2020 19:16:47 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1jSrRy-0007ob-1y; Mon, 27 Apr 2020 02:16:43 +0200 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1jSrRx-0007C0-7Z; Mon, 27 Apr 2020 02:16:41 +0200 Received: from athene.asta.kit.edu ([141.3.145.60] helo=athene.usta.de) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1jSrRw-0008NA-WE; Mon, 27 Apr 2020 02:16:41 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 5ad313a5; Mon, 27 Apr 2020 02:16:40 +0200 (CEST) Date: Mon, 27 Apr 2020 02:16:40 +0200 From: Ingo Schwarze To: "Anthony J. Bentley" Cc: discuss@mandoc.bsd.lv Subject: Re: Fl Fl for long options Message-ID: <20200427001640.GB55740@athene.usta.de> References: <8a57c2f3270c2455@mandoc.bsd.lv> <14105-1587941943.721637@wO-a.W87w.5Fm4> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <14105-1587941943.721637@wO-a.W87w.5Fm4> User-Agent: Mutt/1.12.2 (2019-09-21) Hi Anthony, Anthony J. Bentley wrote on Sun, Apr 26, 2020 at 04:59:03PM -0600: > schwarze@mandoc.bsd.lv writes: >> Log Message: >> ----------- >> While we do not recommend the idiom ".Fl Fl long" for long options >> because it is an abuse of semantic macros for device-specific >> presentational effects > Since we've had this discussion before, I feel like I must reiterate my > disagreement here. "Fl Fl" is a perfectly natural way to represent long > options and it's how I've always done it. > > And again, I still find it incredibly unintuitive that in OpenBSD's > grep(1) manual jumping to the --label tag unintuitively requires > searching for "-label" rather than "label". That had already been fixed for some time before this commit: $ man -O tag=label grep --label=name Print name instead of the filename before lines. [...] The code is in tag.c, function tag_put(). If a word is being automatically tagged and that word starts with "-", "\-", "\&", or "\e", then that prefix is automatically skipped and the rest of the word becomes the tag. This also supports usage like this: $ man -O tag=p roff \p Break the output line at the end of the current word. [...] There is additional code in man_validate that even skips font escapes in such a position; that code is not used for mdoc(7) because nobody in their right mind uses \f in mdoc(7) documents and is somewhat dislike running unnecessary code. For example: $ man -O tag=D cvs -D date_spec Use the most recent revision no later than date_spec (a single [...] $ grep -C1 -m1 date_spec $(man -w 1 cvs) .TP \fB\-D\fP \fIdate_spec\fP > Interpreting "Fl Fl foo" as "empty flag followed by flag foo" simply > doesn't make sense to me. It is not so much something that requires an active interpretation, it already follows from the structure of the language itself. Macros in mdoc(7) and man(7) form a tree structure. In many cases, whether adjacent macros will become siblings or parent and child requires knowledge about the language that isn't apparent from the syntax, and in a few cases, there are equivalent possibilities for the relative positioning of the nodes in the tree that would ultimately result in the same formatting, but that each macro generates a node can hardly be questioned. It is also clear that .Fl is an in-line macro and that in-line macros only extend to the next in-line macro or to the end of the line. So there can be no doubt that the syntactical meaning of "Fl Fl foo" is "an empty flag and a flag foo". > I'm aware there are cases like lprm(1) and > tset(1) that have an empty flag. Even if those were typical examples-- > and they are decidedly not-- Granted. > where in those pages would it ever make > sense to use that empty flag adjacent to another? Is there a single > manpage anywhere that ever uses "Fl Fl" to mean something *other* than > long options? I'm not aware of any, and that is why i decided to implement this syntactical conversion to have "empty flag immediately before non-empty flag" transformed to "flag with double hyphen-minus". > Maybe I just don't understand how this works. But considering the > prevalence of Fl Fl as long option, clearly I'm not alone. I suspect this prevelence resulted from a tradition of "tweak the input until the formatting looks how you want it in the output mode you care about" rather than a tradition of "mark up the text in a logical way and let the formatters decide on a reasonable formatting in each output mode". At least jmc@ repeatedly said that's the way he worked before the advent of mandoc, simply because no other mode of working yielded acceptable formatting during those times. Going forward, some of this discussion has now become moot. With mandoc, ".Fl Fl foo" is now the same for all output modes as ".Fl \-foo". So it's no longer much of a question which one produces better output, except for minor aspects: ".Fl \-foo" is still more robust even with mandoc because stuff that is written correctly in the first place is always more robust than stuff that requires transformation in the validator: for example ".Fl Fl foo" might still cause trouble when you explicitly try to .Tg it because then the two validation routines involved can end up fighting each other, one undoing the benefits of the other (i paid attention though to make sure that automatic tagging works with .Fl Fl). Also, no parser other than mandoc will do the transformation, so ".Fl \-foo" is still more portable. That's why i would still recommend ".Fl \-foo" over ".Fl Fl foo": robustness, portability, and more logical in the first place. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv