Re: syntax of options in man1

[Alejandro Colomar <alx@kernel.org>]

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

Hi Doug,

On 2026-07-16T13:19:20-0400, Douglas McIlroy wrote:
> > I think there should be a separation between an introduction to the
> > entire system (maybe this could be intro(0)), and an introduction to the
> > first section of the manual (intro(1)).
> 
> I agree. In the early days, at least, there was such a section, called
> "getting started". I like the idea of calling it intro(0). The very name
> suggests that there are more intro(.) pages. Elegant!

Thanks!  I've done the split already.

	commit 214f536963b0a108abc54b336d8ac21b4c9f1c7f
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2026-07-17 14:05:19 +0200

	    man/man?/intro.[01]: Split part of intro(1) into a new intro(0)
	    
	    Let's keep intro(1) for introducing just the man1 section, and move the
	    more general introduction of the entire manual to a new intro(0).
	    
	    Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

I haven't yet documented the syntax we were talking about, though.  I'll
think about the best way to document that.

Here's how intro(1) looks like now:

	$ MANWIDTH=64 man man1/intro.1 | cat
	intro(1)            General Commands Manual            intro(1)

	NAME
	     intro - introduction to user commands

	DESCRIPTION
	     Section 1 of the manual describes user commands and tools,
	     for  example,  file manipulation tools, shells, compilers,
	     web browsers, file and image viewers and editors,  and  so
	     on.

	SEE ALSO
	     intro(0)

	Linux man‐pages (unreleased) (date)                    intro(1)


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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