Better man pages #81

New Issue

Open

opened 2024-03-19 02:52:01 +00:00 by emma · 2 comments

emma commented

2024-03-19 02:52:01 +00:00

Owner

For readability, manpages should list options not in text blocks but in definition-style blocks (example from pacman(1):

OPERATIONS
       -D, --database
           Operate on the package database. This operation allows you to
           modify certain attributes of the installed packages in pacman’s
           database. It also allows you to check the databases for internal
           consistency. See Database Options below.

       -Q, --query
           Query the package database. This operation allows you to view
           installed packages and their files, as well as meta-information
           about individual packages (dependencies, conflicts, install date,
           build date, size). This can be run against the local package
           database or can be used on individual package files. In the first
           case, if no package names are provided in the command line, all
           installed packages will be queried. Additionally, various filters
           can be applied on the package list. See Query Options below.

       -R, --remove
           Remove package(s) from the system. Groups can also be specified to
           be removed, in which case every package in that group will be
           removed. Files belonging to the specified package will be deleted,
           and the database will be updated. Most configuration files will be
           saved with a .pacsave extension unless the --nosave option is used.
           See Remove Options below.

       -S, --sync
           Synchronize packages. Packages are installed directly from the
           remote repositories, including all dependencies required to run the
           packages. For example, pacman -S qt will download and install qt
           and all the packages it depends on. If a package name exists in
           more than one repository, the repository can be explicitly
           specified to clarify the package to install: pacman -S testing/qt.
           You can also specify version requirements: pacman -S "bash>=3.2".
           Quotes are needed, otherwise the shell interprets ">" as
           redirection to a file.

For readability, manpages should list options not in text blocks but in definition-style blocks (example from `pacman(1)`: ``` OPERATIONS -D, --database Operate on the package database. This operation allows you to modify certain attributes of the installed packages in pacman’s database. It also allows you to check the databases for internal consistency. See Database Options below. -Q, --query Query the package database. This operation allows you to view installed packages and their files, as well as meta-information about individual packages (dependencies, conflicts, install date, build date, size). This can be run against the local package database or can be used on individual package files. In the first case, if no package names are provided in the command line, all installed packages will be queried. Additionally, various filters can be applied on the package list. See Query Options below. -R, --remove Remove package(s) from the system. Groups can also be specified to be removed, in which case every package in that group will be removed. Files belonging to the specified package will be deleted, and the database will be updated. Most configuration files will be saved with a .pacsave extension unless the --nosave option is used. See Remove Options below. -S, --sync Synchronize packages. Packages are installed directly from the remote repositories, including all dependencies required to run the packages. For example, pacman -S qt will download and install qt and all the packages it depends on. If a package name exists in more than one repository, the repository can be explicitly specified to clarify the package to install: pacman -S testing/qt. You can also specify version requirements: pacman -S "bash>=3.2". Quotes are needed, otherwise the shell interprets ">" as redirection to a file. ```

trinity was assigned by emma

2024-03-19 02:52:17 +00:00

emma added the

enhancement

label 2024-03-19 02:52:21 +00:00

trinity commented

2024-03-19 03:57:28 +00:00

Owner

What roff syntax should be used to accomplish this?

I tend to use a very narrow subset of roff as it's convoluted and documentation is difficult to maintain.

What roff syntax should be used to accomplish this? I tend to use a very narrow subset of roff as it's convoluted and documentation is difficult to maintain.

trinity commented

2024-03-26 22:04:12 +00:00

Owner

Relevant to #41.

emma self-assigned this 2024-04-27 19:00:14 +00:00

trinity was unassigned by emma

2024-04-27 19:00:14 +00:00