SUSE/doc-styleguide

"man page" or "manual page"

cwickert opened this issue · 5 comments

cwickert commented

@chabowski brought this up in the weekly team meeting: Should we say "man page" (as in the terminology section of the style guide) or "manual page" (official term, see man man).

Additional questions for the respective section of the style guide:

  1. The style guide already says the man page of <command>command</command> (and the info page of <command>command</command>), but we don't enforce this. We also have:
  • the <command>umask</command> man page. (pretty often)
  • For more information on <command>chrt</command>, see its man page.
  • the respective man pages
  • the man page
  1. Should we write out the command to call the man page (<command>man foo</command>)? Currently this is only mandatory for commands with different multiple man pages (<command>man 1 foo</command>)
cwickert commented

My personal take on this:

  1. I like 'manual page' better, but I'm not sure it's worth the effort. If we switch to writing out the command to call the man page, this question becomes moot.
  2. Both man page of <command>umask</command> and <command>umask</command> man page work for me. I like the letter better, but I don't think we need to be overly strict here. Only the man page should be forbidden.
  3. Stick with the current recommendation.

Change my mind! ;-)

dariavladykina commented

@cwickert, I agree to stick with the current recommendation :-) As for writing out the command to call the man page, can I ask to do it? Thanks!

dariavladykina commented

Stylewich agreed to not take action in the style guide and to add an AI for @janajaeger - please update the Smart Docs basics (readme) with the info on the foo command. Thanks!

janajaeger commented

Stylewich agreed to not take action in the style guide and to add an AI for @janajaeger - please update the Smart Docs basics (readme) with the info on the foo command. Thanks!

I'd like to hand this back to Stylewich and suggest we stick to what is already in there.
a) we forbid the use of "manual page" (see the Terminology section)
b) encourage writers to use the "man page of something and to only write out the command if we need to refer to a certain category.

Please, just let's apply the rules already in the SG for this one and not make up new ones that overcomplicate things!

dariavladykina commented

Closing this because, as we said, there is enough info about the man page in DSG.