From owner-freebsd-hackers@freebsd.org Tue Jun 9 19:37:18 2020 Return-Path: Delivered-To: freebsd-hackers@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id B24F333A2DA for ; Tue, 9 Jun 2020 19:37:18 +0000 (UTC) (envelope-from steffen@sdaoden.eu) Received: from sdaoden.eu (sdaoden.eu [217.144.132.164]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 49hL3x2VzRz4TFL; Tue, 9 Jun 2020 19:37:17 +0000 (UTC) (envelope-from steffen@sdaoden.eu) Received: by sdaoden.eu (Postfix, from userid 1000) id 9DA9D16054; Tue, 9 Jun 2020 21:37:14 +0200 (CEST) Date: Tue, 09 Jun 2020 21:37:14 +0200 From: Steffen Nurpmeso To: Ian Lepore Cc: Yuri Pankov , freebsd-hackers@freebsd.org, "Rodney W. Grimes" Subject: Re: svn commit: r361940 - head/usr.bin/mkimg Message-ID: <20200609193714.lkpZS%steffen@sdaoden.eu> In-Reply-To: <1743df590639dc61b2b4216c81677851d2ee1312.camel@freebsd.org> References: <202006082111.058LBYfj075205@repo.freebsd.org> <20200608211940.qrR5l%steffen@sdaoden.eu> <20200609141319.u7QUq%steffen@sdaoden.eu> <1743df590639dc61b2b4216c81677851d2ee1312.camel@freebsd.org> Mail-Followup-To: Ian Lepore , Yuri Pankov , freebsd-hackers@freebsd.org, "Rodney W. Grimes" User-Agent: s-nail v14.9.19-56-g9975bde7 OpenPGP: id=EE19E1C1F2F7054F8D3954D8308964B51883A0DD; url=https://ftp.sdaoden.eu/steffen.asc; preference=signencrypt BlahBlahBlah: Any stupid boy can crush a beetle. But all the professors in the world can make no bugs. X-Rspamd-Queue-Id: 49hL3x2VzRz4TFL X-Spamd-Bar: - Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of steffen@sdaoden.eu designates 217.144.132.164 as permitted sender) smtp.mailfrom=steffen@sdaoden.eu X-Spamd-Result: default: False [-1.68 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.96)[-0.959]; FROM_HAS_DN(0.00)[]; RCPT_COUNT_THREE(0.00)[4]; TO_DN_SOME(0.00)[]; R_SPF_ALLOW(-0.20)[+a]; MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[sdaoden.eu]; NEURAL_HAM_LONG(-0.91)[-0.911]; TO_MATCH_ENVRCPT_SOME(0.00)[]; NEURAL_HAM_SHORT(-0.51)[-0.509]; MID_CONTAINS_FROM(1.00)[]; RCVD_COUNT_ZERO(0.00)[0]; FROM_EQ_ENVFROM(0.00)[]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:15987, ipnet:217.144.128.0/20, country:DE] X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 09 Jun 2020 19:37:18 -0000 Ian Lepore wrote in <1743df590639dc61b2b4216c81677851d2ee1312.camel@freebsd.org>: |On Tue, 2020-06-09 at 16:13 +0200, Steffen Nurpmeso wrote: |> I for one think Fl Fl is absolutely valid, where is the problem? |> If you go that route that Ingo (it is Ingo) brings into the world |> here (which counteracts many, many real-life manuals), then just |> reach into the macros and check how many characters the argument |> to Fl has, after all Fl is meant to document getopt-style things. |> If it is one, it is a short option, if it has more, it is a long |> one. Short options have one dash, long have two, that is the |> convention. | |It may be a convention, but it is not a standard that is universally |followed, as "man clang" or "man gcc" will show you. | |-- Ian --End of <1743df590639dc61b2b4216c81677851d2ee1312.camel@freebsd.org> Rodney W. Grimes wrote in <202006091814.059IErtW052230@gndrsh.dnsmgr.net>: |> Mateusz Piotrowski wrote in |> <202006082111.058LBYfj075205@repo.freebsd.org>: |>|Author: 0mp (doc,ports committer) |>|Date: Mon Jun 8 21:11:34 2020 |>|New Revision: 361940 |>|URL: https://svnweb.freebsd.org/changeset/base/361940 |>| |>|Log: |>| Use Fl instead of Ar for long flags |> ... |>|-.Ar --formats | --schemes | --version |>|+.Fl -formats | Fl -schemes | Fl -version |> |> Ingo Schwarze of mandoc has in the meanwhile committed support for |> ".Fl Fl", which is the term that seems to be most widely used for |> long options, for example |> |> .Fl Fl formats |> |> It also works just fine for groff, the real roff macros that is. | |While this produces the correct typographic output, I believe |it to be counter to the intent of roff to be a lexographical |expression of content. It would probably be wise if one |wants to preserve the intent of roff to introduce a new macro |that describes the doublt dash long options. ... |Rod Grimes rgrimes@freeb\ |sd.org --End of <202006091814.059IErtW052230@gndrsh.dnsmgr.net> Good, despite being not able to deal with programs which use their own style of options (lynx(1) would have been another example), the .length example will not work out for my own thing either, to handle the display of all the one-letter options without arguments, for example (here the optional ones: .Op Fl DdEFinv~#). I still stand by my opinion that Fl Fl gives more context than Fl \-, and keeps all the dirty logic in the macro set where it belongs. And is an easy rule to remember, because the above changeset turns something "wrong" into something that is at least doubtful, it will render ugly dependent on the output device, too. roff maybe, mdoc however is really lifted, it results in terrible constructs like the _unbelievable_ .Oo : Ns Fl S\0 Ns Ar var Ns Oo Ns = Ns Ar value Ns Oc Ns : Ns Oc At least it is "better" / more explicit than the man macros. P.S.: interesting that clang is noted as an example for manual pages, as it does not truly offer them as far as i know. When i look around more and more applications do not ship tarballs with readily prepared manuals at all, so you need a fully blown local "doc" environment to generate them, python / sphinx or docbook or asciidoc are common. This becomes a problem for self-builders, on CRUX-Linux some packages start shipping without any manuals (info always has been unwanted there) in order to reduce the build time dependencies. clang is one of those. --steffen | |Der Kragenbaer, The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt)