From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 21b8ba73 for ; Thu, 25 Apr 2019 12:02:03 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hJhl3-00047h-Rv; Thu, 25 Apr 2019 19:02:02 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hJhl2-00024u-IL; Thu, 25 Apr 2019 19:02:00 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hJhl2-0004U2-Cv; Thu, 25 Apr 2019 19:02:00 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 543b3a35; Thu, 25 Apr 2019 19:02:00 +0200 (CEST) Date: Thu, 25 Apr 2019 19:02:00 +0200 From: Ingo Schwarze To: Stephen Gregoratto Cc: discuss@mandoc.bsd.lv Subject: Re: docbook2mdoc-1.0.0 released Message-ID: <20190425170200.GC66649@athene.usta.de> References: <20190417192435.GA10272@athene.usta.de> <20190420190331.GA36463@www.stare.cz> <20190421112632.z7fawjteacah4ypt@BlackBox> 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: <20190421112632.z7fawjteacah4ypt@BlackBox> User-Agent: Mutt/1.8.0 (2017-02-23) Hi Stephen, Stephen Gregoratto wrote on Sun, Apr 21, 2019 at 09:26:32PM +1000: > My vote goes to Fl -option due to how mandoc handles Fl Fl > in HTML output. That isn't a very strong argument. Best markup practice ought to be governed by what the markup means, not by how individual output modes represent it. > Take this example: > > .Bl -tag -width Ds > .It Fl Fl option > Foo > .It Fl -option > Bar > .El > > On mandoc 1.14.5, the option list is output as follows: > >
>
> --option >
>
Foo
>
> >
>
Bar
>
> > Notice how the Fl -option gets enclosed in an "" link whilst the Fl > Fl option doesn't? This comes in handy when you have to reference the > option later as it can link to it's definition in the option list. Right. This is because in the case of ".It Fl", mandoc is able to figure out that this is likely the authoritative description of the command line option. By contrast, in the case of ".It Fl Fl", mandoc is not able to figure out what is going on. The first "Fl" is empty, so it cannot be linked to. A later "Fl" in ".It" cannot safely be linked to either. If "Fl" appears in the middle of other macros, that is usually *not* the authoritative description of the option. Hence mandoc writes no permalink, nor a tag in terminal output mode. So in an indirect sense, your argument is sound after all. The idiom "Fl Fl" is not a good idea because it obscures the semantics. The loss of the permalink (and of the tag in terminal output) is a symptom of that degraded semantic clarity. > On reflection this does seem like a workaround for buggy output. No, the output is not buggy, but carefully designed. It is not a bug, but a feature that not every .Fl macro creates a permalink. As a matter of fact, the majority of .Fl macros should not create permalinks. Most of them are merely passing mentions of options in the middle of text describing other matters. Macros only create permalinks when there are clear indications that they introduce an authoritative description. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv