Title: Theory / Unimportant / CS / Softw / Manual
Tags: récupéré mid1516974248815

Question: Constraint on documentation
Answer: It should be accessible
Page: https://www.tldp.org/HOWTO/Man-Page/q1.html
Answer2: It should be reliable
Answer3: It should be accurate

Question: Why write documentation
Answer: we want others to be able to use our program, library function or whatever we have written and made available.
Page: https://www.tldp.org/HOWTO/Man-Page/q1.html

Name: Section
Definition: A category of man pages
Page: https://www.tldp.org/HOWTO/Man-Page/q2.html
Section: 2
Context: man
Notation: single letter

Variable: foo.b
Meaning: The file for section b and command foo
Page: https://www.tldp.org/HOWTO/Man-Page/q2.html
Context: man
Section: 2
Kind: file

Variable: foo.fiz
Meaning: The file for section b and command foo, for an usage of kind biz (for example, tk program, X11 program)
Page: https://www.tldp.org/HOWTO/Man-Page/q2.html
Context: man
Section: 2
Kind: file

Variable: MANPATH
Meaning: Base directory for man files
Page: https://www.tldp.org/HOWTO/Man-Page/q2.html
Context: man
Section: 2
Kind: Environment variable

Name: Base directory
Definition: a directory o for each non-empty section o
Page: https://www.tldp.org/HOWTO/Man-Page/q2.html
Section: 2
Context: man
Definition2: directories fmt for documentation already displayed in some format fmt
Conjdef: A directory with
Definition3: a file whatis
Definition4: nothing else

Instruction: .SH NAME foo \- frobnicate the bar library
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Effect: indicates the name of program, and one-line description of the functionality
Context: man
Section: 3
Intuition: Name section

Name: Synopsis section
Definition: give a short overview on available program options.
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man
Definition2: For functions this sections lists corresponding include files and the prototype so the programmer knows the type and number of arguments as well as the return type.
Conjdef: Both

Name: Description section
Definition: Here's where you write down all your knowledge. This is the Hall Of Fame. Win other programmers' and users' admiration by making this section the source of reliable and detailed information. Explain what the arguments are for, the file format, what algorithms do the dirty jobs.
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man

Name: Option section
Definition: .gives a description of how each option affects program behaviour.
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man

Name: File section
Definition: Lists files the program or function uses.
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man

Name: Environment section
Definition: lists all environment variables that affect your program or function and tells how, of course.
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man
Example: variables holding pathnames, filenames or default options.

Name: Environment section
Definition: give an overview of the most common error messages from your program and how to cope with them
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man

Name: Bugs section
Definition: Describe here the limitations, known inconveniences and features that others may regard as misfeatures
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man

Name: Author section
Definition: section stating who to blame, to send bug report
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man

Name: See also section
Definition: List of related man pages in alphabetical order.
Page: https://www.tldp.org/HOWTO/Man-Page/q3.html
Section: 3
Context: man

Instruction: .so foo
Page: https://www.tldp.org/HOWTO/Man-Page/q4.html
Effect: State to look at file foo instead of the current file
Context: man
Section: 4

Question: How to use a same man page for multiple programs/names
Answer: Use .so in the other name to state to look at the first name
Page: https://www.tldp.org/HOWTO/Man-Page/q4.html
Section: 4
Context: man