linux-man.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Thaddeus H. Black" <thb@debian.org>
To: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
Cc: linux-man@vger.kernel.org,
	Michael Kerrisk <mtk.manpages@gmail.com>,
	"G. Branden Robinson" <g.branden.robinson@gmail.com>
Subject: Re: [PATCH] filename.7: new manual page
Date: Thu, 9 Sep 2021 02:15:24 +0000	[thread overview]
Message-ID: <YTluPPbquS6ZHmHL@b-tk.org> (raw)
In-Reply-To: <1543a191-66f9-3cb5-1903-277242e9204c@gmail.com>

[-- Attachment #1: Type: text/plain, Size: 2258 bytes --]

On Wed, Sep 08, 2021 at 05:45:43PM +0200, Alejandro Colomar (man-pages) wrote:
> > Question 1:  do you happen to know of a good example of an existing
> > manual page that already does this?  If you did, then I could follow the
> > example.  Otherwise, it might be tricky, for the existing subsections
> > already have tagged paragraphs and other structure within them.
> > Perhaps .RS/.RE could be used.  I am not sure.
> 
> I don't know of a page that does this, and some of them are a bit
> inconsistent, so I'd have to search through the source code of the pages to
> find one that is a perfect example.  So I'll write/draw a schema here:
> 
> You could do it like this:
> 
> .TP
> 	tag 1
> .PP
> 		paragraph 1.1
> .IP
> 		paragraph 1.2
> .IP
> 		paragraph 1.3
> .RS
> .TP
> 		tag 1.4
> .PP
> 			paragraph 1.4.1
> .IP
> 			paragraph 1.4.2
> .RS
> .TP
> 			tag 1.4.3
> .PP
> 				paragraph 1.4.3.1
> .IP
> 				paragraph 1.4.3.2
> .IP
> 				paragraph 1.4.3.3
> .RE
> .IP
> 			paragraph 1.4.4
> .RE
> .IP
> 		paragraph 1.5
> 
> 
> Was it helpful?

Yes but it does not do exactly what you want.  However, after some
reading and experimentation, I find that the following does exactly what
you want (if I correctly understand what you want).

    .\" The .SSS macro introduces a subsubsection
    .\" as the .SS macro introduces a subsection.
    .de1 SSS
    .  if !r SSS_SN_ORIG .nr SSS_SN_ORIG \\n[SN]
    .  nr SN (2 * \\n[SSS_SN_ORIG])
    .  SS \&\\$*
    .  nr SN (\\n[SSS_SN_ORIG])
    ..
    .TH ABC 7 1970-01-01 "Linux" "Linux Programmer's Manual"
    .SH SECTION FOO
    .PP
    Foo flargh.
    .SS Subsection bar
    .PP
    Bar blargh.
    .SSS Subsubsection baz
    .PP
    Baz mnargh.

Result:

    ABC(7)                 Linux Programmer's Manual                 ABC(7)

    SECTION FOO
           Foo flargh.

       Subsection bar
           Bar blargh.

          Subsubsection baz
           Baz mnargh.

    Linux                          1970-01-01                        ABC(7)

On the PDF output device, the result is similar, though the narrow
offset (only 1.2en) between "Subsubsection baz" and "Baz mnargh" is
slightly unappealing in the PDF.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

  reply	other threads:[~2021-09-09  2:37 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-09-06 11:40 [PATCH] filename.7: new manual page Thaddeus H. Black
2021-09-06 14:21 ` Alejandro Colomar (man-pages)
2021-09-06 16:59   ` G. Branden Robinson
2021-09-06 21:47     ` Alejandro Colomar (man-pages)
2021-09-08  3:54       ` G. Branden Robinson
2021-09-08 14:56   ` Thaddeus H. Black
2021-09-08 15:45     ` Alejandro Colomar (man-pages)
2021-09-09  2:15       ` Thaddeus H. Black [this message]
2021-09-09  2:45         ` Thaddeus H. Black
2021-09-09  7:24         ` [PATCH 1/3] Remove unnecessary .P after .S[HS] Alejandro Colomar
2021-09-09  7:24         ` [PATCH 2/3] Fix indentation of paragraph, which continues talking about \0 Alejandro Colomar
2021-09-09  7:24         ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
2021-09-09  7:28           ` [PATCH] .P -> .PP Alejandro Colomar
2021-09-12 14:20           ` [PATCH 3/3] Use subsections instead of sections Thaddeus H. Black
2021-09-12 14:49             ` Alejandro Colomar (man-pages)
2021-09-12 14:56               ` Alejandro Colomar (man-pages)
2021-09-12 15:22                 ` Thaddeus H. Black
2021-09-12 18:49                   ` G. Branden Robinson
2021-09-12 18:12                 ` G. Branden Robinson
2021-09-12 22:39                   ` Alejandro Colomar (man-pages)

Reply instructions:

You may reply publicly 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=YTluPPbquS6ZHmHL@b-tk.org \
    --to=thb@debian.org \
    --cc=alx.manpages@gmail.com \
    --cc=g.branden.robinson@gmail.com \
    --cc=linux-man@vger.kernel.org \
    --cc=mtk.manpages@gmail.com \
    /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
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).