1

I'm learning to edit man pages. I've just noted SEE ALSO part in source file consists of separate lines (displayed as one long line by man). Any value in that? Or I can as well put long list of references on one line?

P.S. Easy related questions just in bulk with main one (feel free to ignore). In some source files lines end with "," (grep), some do not (cgcreate). Start with .BR (grep) or not (cgcreate). Any meaning except for indentation?

1 Answer 1

2

The value in keeping references on separate lines is that when references are added or removed, that change appears on its own, instead of reworking the whole line every time.

My suggestion is to follow the man-pages project conventions:

A comma-separated list of related man pages, possibly followed by other related pages or documents.

The list should be ordered by section number and then alphabetically by name. Do not terminate this list with a period.

.BR is used so that man page titles are bold, but sections not.

5
  • "when references are added or removed". Is it when e.g. apt-get installs a package and it is programmed to add some? If so, I wonder why when installed cgroups-tools it does not seem to had added references to man page of cgroups for its utilities/commands. Sep 22, 2023 at 8:15
  • "alphabetically by name.". IMO ordered by relevance is more useful; contra argument might be: what is relevant to one user might be not for the other. Sep 22, 2023 at 8:17
  • With “when references are added or removed”, I was only referring to the maintenance of the man pages themselves — i.e. their editorial life (which is really the only circumstance where the man page source code really matters). I’m thinking of the version control history for example, or the legibility of patches. Sep 22, 2023 at 8:42
  • Ok. I was hoping a package updates man pages of another to add references if relevant. I see I need to do that myself on my system - hence editing to be continued. "Obviously" it is not a good practice to add references to commands which require additional packages to be installed (IIRC I've not seen that yet). Sep 22, 2023 at 8:48
  • 1
    Packages aren’t allowed to change other packages’ man pages; I agree it would be useful... Sep 22, 2023 at 9:32

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .