RGBCube/serenity
1
Fork 0
mirror of https://github.com/RGBCube/serenity synced 2025-05-31 20:58:11 +00:00
Code Issues Activity Actions

Base: Document manpage structure separately

Browse source 
This section is now removed from Help(1) and man(1).
This commit is contained in:
kleines Filmröllchen 2022-12-14 15:47:50 +01:00 • committed by Andrew Kaster
parent 2d08e53493
commit f824a67b3b
4 changed files with 63 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

17
Base/usr/share/man/man1/Help.md
View file

@ -18,21 +18,6 @@ $ Help file
`Help` is Serenity's digital manual, the GUI counterpart to `man`.
It lets you search for and read manual pages (or "man pages").
## Sections
The SerenityOS manual is split into the following *sections*, or *chapters*:
1. User Programs
2. System Calls
3. Library Functions
4. Special Files
5. File Formats
6. Games
7. Miscellanea
8. Sysadmin Tools
Sections are subject to change in the future.
## Examples
To open Help:
@ -62,4 +47,4 @@ this man page should be located at `/usr/share/man/man1/Help.md`.
## See Also
* [`man`(1)](help://man/1/man) To read these same man pages from the terminal
* [`man`(7)](help://man/7/man) For an overview on how manpages are organized

17
Base/usr/share/man/man1/man.md
View file

@ -15,21 +15,6 @@ $ man section page
or man pages for short, from the SerenityOS manual. You're reading
the manual page for `man` program itself right now.
## Sections
The SerenityOS manual is split into the following *sections*, or *chapters*:
1. User Programs
2. System Calls
3. Library Functions
4. Special Files
5. File Formats
6. Games
7. Miscellanea
8. Sysadmin Tools
Sections are subject to change in the future.
## Examples
To open documentation for the `echo` command:
@ -54,3 +39,5 @@ this man page should be located at `/usr/share/man/man1/man.md`.
## See Also
* [`less`(1)](help://man/1/less) For the terminal pager that `man` uses by default
* [`Help`(1)](help://man/1/Help) To read these same man pages in a GUI
* [`man`(7)](help://man/7/man) For an overview on how manpages are organized

4
Base/usr/share/man/man7/Help-index.md
View file

@ -2,7 +2,7 @@
## Welcome to the SerenityOS on-line help system!
This is **Help**, the built-in documentation viewer for the SerenityOS desktop environment. If you prefer a command-line interface, the [man](help://man/1/man) command offers a text-only view of the same library.
This is **Help**, the built-in documentation viewer for the SerenityOS desktop environment. If you prefer a command-line interface, the [`man`(1)](help://man/1/man) command offers a text-only view of the same library.
---
@ -10,6 +10,8 @@ Documentation is divided into traditional Unix-style manual categories. Use the
There's also a full-text search option under the **Search** tab.
If you want more information on the structure of the manual system, take a look at [`man(7)`](help://man/7/man).
---
Thank you for using ***SerenityOS Help!***

57
Base/usr/share/man/man7/man.md Normal file
View file

@ -0,0 +1,57 @@
## Name
man - SerenityOS manual system
## Description
The SerenityOS manual pages, or "man pages", document various parts of the operating system for users and developers. They are one of the two parts of the SerenityOS documentation.
The other part of the SerenityOS documentation is the developer documentation, which can be found in the `Documentation` folder in the repository ([online link](https://github.com/SerenityOS/serenity/tree/master/Documentation)). The developer documentation is focused on setting up a SerenityOS installation and workflow, as well as contributing to its development.
Note that documentation might cover standardized topics (such as standard POSIX C library functions) or SerenityOS-specific extensions (such as custom file formats). SerenityOS intends to be spec-complaint with industry standard specifications. Non-compliance with a particular specification should be documented in the relevant sections.
### Programs
There are three ways of accessing the manual pages:
- [`Help`(1)](help://man/1/Help) provides a graphical user interface for the man pages.
- [`man`(1)](help://man/1/man) implements the standard POSIX utility by accessing the man pages in the terminal.
- You can also choose to open the underlying Markdown files (see [Organization](#organization)) directly.
### Organization
Each SerenityOS manual page is a Markdown (.md) file under [`/usr/share/man`](/usr/share/man). The [main sections](#sections) live in the subdirectories `man1` through `man8`. Subsections are found within these directories.
#### Sections
The SerenityOS manual is split into the following _sections_, or _chapters_:
1. User Programs - manuals for regular user applications and utilities
2. System Calls - SerenityOS system call interface documentation
3. Library Functions - SerenityOS C library function documentation
4. Special Files - documentation for pseudo-files of the SerenityOS virtual file system
5. File Formats - documentation for SerenityOS-specific file formats
6. Games - manuals for SerenityOS games
7. Miscellanea - various documentation that fits in no other category
8. Sysadmin Tools - manuals for services and utilities intended for system administration
Sections are subject to change in the future.
#### Subsections
Subsections exist to organize various large collections of topics within one main section. Subsections have their own pages (often a table of contents or general overview), so they are a category and a page at the same time. Subsections can be arbitrarily nested.
The currently existing subsections are not listed here, as they are subject to frequent change.
#### Naming
Manpages are named via standard POSIX convention, where the section number follows the page name in brackets. For example, this page is called `man(7)`, but there's also a page called `man(1)` (the _program_ named `man`) and a page named [`Mitigations(7)`](help://man/7/Mitigations). This naming convention also applies to subsections.
For pages in subsections, conventional directory notation with slashes is used. For example, the page `Widget-Button` in the subsection `GML(5)` has the full name `GML/Widget-Button(5)`.
When you open a page via command-line arguments, the section is specified separately before the page name, for example `7 man`, `1 man`, or `7 Mitigations`.
## See Also
- [`man`(1)](help://man/1/man) To read manpages in the terminal
- [`Help`(1)](help://man/1/Help) To read manpages in a GUI