Util-Linux Archive on lore.kernel.org
 help / color / Atom feed
From: Karel Zak <kzak@redhat.com>
To: J William Piggott <elseifthen@gmx.com>
Cc: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>, util-linux@vger.kernel.org
Subject: Re: [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes
Date: Fri, 3 Jan 2020 12:48:14 +0100
Message-ID: <20200103114814.2roeaoes2uu3enxu@10.255.255.10> (raw)
In-Reply-To: <nycvar.YAK.7.76.2001021131520.1385@zhn.tzk.pbz>

On Thu, Jan 02, 2020 at 11:52:06AM -0500, J William Piggott wrote:
> On Thu, 2 Jan 2020, Bjarni Ingi Gislason wrote:
> > Comment the font-escape line and
> > add the font-macro line after it.
> 
>  If I had submitted a patch like that it would have been rejected
>  (although I would not do that to a production man page anyway).

Well, frankly... I don't like man-page (re)formatting patches :-) 

It's maintainer's nightmare -- always is there someone who hates the
change, it's difficult review all the details and keep all consistent
if you have large collection of man pages from different
sources/authors, etc.

For me the best would be to maintain *content* in some formatting
independent data format like AsciiDoc or DocBook, and before release
or during package build process generate wanted output according a
user-specified template; it's only a way how to support user or distro
specific point of view.

For example asciidoctor (AsciiDoc backend) is actively maintained and
used by projects like github. Not sure about readability of the final
man pages, but it seems that AsciiDoc -> DocBook -> man page is
possible way.

And for example systemd guys maintain man pages directly in XML DocBook.

IMHO it's way to go rather than for ever play "color of bike shed"
game with our man pages.

“Content is King” :-) Volunteers?

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com


      reply index

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-12-16 22:20 Bjarni Ingi Gislason
2019-12-17 20:43 ` J William Piggott
2020-01-02  0:17   ` Bjarni Ingi Gislason
2020-01-02 16:52     ` J William Piggott
2020-01-03 11:48       ` Karel Zak [this message]

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200103114814.2roeaoes2uu3enxu@10.255.255.10 \
    --to=kzak@redhat.com \
    --cc=bjarniig@rhi.hi.is \
    --cc=elseifthen@gmx.com \
    --cc=util-linux@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Util-Linux Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/util-linux/0 util-linux/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 util-linux util-linux/ https://lore.kernel.org/util-linux \
		util-linux@vger.kernel.org
	public-inbox-index util-linux

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.util-linux


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git