Date: Tue, 09 Jun 2020 21:37:14 +0200 From: Steffen Nurpmeso <steffen@sdaoden.eu> To: Ian Lepore <ian@freebsd.org> Cc: Yuri Pankov <yuripv@yuripv.dev>, freebsd-hackers@freebsd.org, "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net> 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> <bd5e499e-36a7-51cc-4130-c29a344b580d@yuripv.dev> <20200609141319.u7QUq%steffen@sdaoden.eu> <1743df590639dc61b2b4216c81677851d2ee1312.camel@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20200609193714.lkpZS%steffen>