Editing Man page (section)

==Authoring==
Manual pages can be written either in the old {{code|man}} macros or the new {{code|doc}} macros.<ref>{{man|5|groff_tmac|ManKier}}</ref> The {{code|man}} macro set provides minimal [[rich text]] functions, with directives for the title line, section headers, (bold, small or italic) fonts, paragraphs and adding/reducing indentation.<ref>{{man|7|man|ManKier}}</ref> The newer {{code|mdoc}} language is more semantic in nature, and contains specialized macros for most standard sections such as program name, synopsis, function names, and the name of the authors. This information can be used to implement a [[semantic search]] for manuals by programs such as [[mandoc]]. Although it also includes directives to directly control the styling, it is expected that the specialized macros will cover most of the use-cases.<ref name=mdoc-7>{{man|7|mdoc|FreeBSD}}</ref> Both the mandoc and the groff projects consider {{code|mdoc}} the preferred format for new documents.<ref>{{cite web |title=Groff Mission Statement - 2014 |url=https://www.gnu.org/software/groff/groff-mission-statement.html |website=www.gnu.org |quote=Concurrent with work on man(7), mdoc(7) will be actively supported and its use promoted. |access-date=2021-01-02 |archive-date=2020-12-03 |archive-url=https://web.archive.org/web/20201203121306/https://www.gnu.org/software/groff/groff-mission-statement.html |url-status=live }}</ref>

Although man pages are, to troff, text laid out using 10-point [[Roman type]], this distinction is usually moot because man pages are viewed in the terminal (TTY) instead of laid out on paper. As a result, the "small font" macro is seldom used.<ref>{{cite web |title=man |url=https://www.gnu.org/software/groff/manual/html_node/man.html |website=The GNU Troff Manual |access-date=31 December 2019 |archive-date=24 December 2019 |archive-url=https://web.archive.org/web/20191224124039/https://www.gnu.org/software/groff/manual/html_node/man.html |url-status=live }}</ref> On the other hand, bold and italic text is supported by the terminal via [[ECMA-48]], and groff's {{code|grotty}} does emit them as requested when it detects a supporting terminal. The BSD mandoc however only supports bold and underlined (as a replacement for italics) text via the typewriter backspace-then-overstrike sequence, which needs to be translated into ECMA-48 by {{code|less}}.<ref>{{cite web |title=Italics and colour in manual pages on a nosh user-space virtual terminal |url=https://jdebp.uk/Softwares/nosh/italics-in-manuals.html |website=jdebp.eu |access-date=2021-01-21 |archive-date=2021-01-28 |archive-url=https://web.archive.org/web/20210128033617/https://jdebp.uk/Softwares/nosh/italics-in-manuals.html |url-status=live }}</ref><ref>{{man|1|mandoc|FreeBSD}}. "Font styles are applied by using back-spaced encoding..."</ref>

Some tools have been used to convert documents in a less contrived format to manual pages. Examples include GNU's {{code|help2man}}, which takes a {{code|--help}} output and some additional content to generate a manual page.<ref>{{cite web |title=help2man Reference Manual |url=https://www.gnu.org/software/help2man |access-date=5 March 2023 |archive-date=6 March 2023 |archive-url=https://web.archive.org/web/20230306093151/https://www.gnu.org/software/help2man/ |url-status=live }}</ref> The manual would be barely more useful than the said output, but for GNU programs this is not an issue as texinfo is the main documentation system.<ref>{{cite web |title=Man Pages (GNU Coding Standards) |url=https://www.gnu.org/prep/standards/html_node/Man-Pages.html |website=www.gnu.org |access-date=2023-03-05 |archive-date=2023-03-05 |archive-url=https://web.archive.org/web/20230305170922/https://www.gnu.org/prep/standards/html_node/Man-Pages.html |url-status=live }}</ref> A number of tools, including [[pandoc]], ronn, and md2man support conversion from [[Markdown]] to manual pages. All these tools emit the {{code|man}} format, as Markdown is not expressive enough to match the semantic content of {{code|mdoc}}. [[DocBook]] has an inbuilt man(7) converter &ndash; of appalling quality, according to mandoc's author<ref>{{cite web |author=Ingo Schwarze |title=New mandoc -mdoc -T markdown converter |url=https://undeadly.org/cgi?action=article&sid=20170304230520 |website=undeadly.org |access-date=2023-03-05 |archive-date=2023-03-05 |archive-url=https://web.archive.org/web/20230305170920/https://undeadly.org/cgi?action=article&sid=20170304230520 |url-status=live }} &ndash; for specific complaints by the author, see {{cite mailing list |url=https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html |title=Re: Groff man pages (tangential to Future Redux) |author=Ingo Schwarze |date=28 February 2014 |mailing-list=Groff |archive-url=https://web.archive.org/web/20230305171936/https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html |archive-date=2023-03-05 |url-status=live}}</ref> who wrote a separate mdoc(7) converter.

Man pages are usually written in English, but translations into other languages may be available on the system. The GNU {{code|man-db}} and the mandoc {{code|man}} is known to search for localized manual pages under subdirectories.<ref>{{cite web |title=command line - Linux man pages in different languages |url=https://askubuntu.com/a/1113662 |website=Ask Ubuntu |access-date=2020-05-05 |archive-date=2023-03-11 |archive-url=https://web.archive.org/web/20230311130846/https://askubuntu.com/questions/1113648/linux-man-pages-in-different-languages/1113662 |url-status=live }}</ref><ref name=mk>{{man|1|man|ManKier}}</ref>{{rp|at=Overview}}<ref name=FBSD/>

=== Alternatives ===
Few alternatives to <code>man</code> have enjoyed much popularity, with the possible exception of [[GNU Project|GNU Project's]] "<code>[[Texinfo|info]]</code>" system, an early and simple [[hypertext]] system.  There is also a third-party effort known as [[TLDR pages]] (<code>tldr</code>) that provides simple examples for common use cases, similar to a [[cheatsheet]].<ref>{{cite web |title=TLDR pages |url=https://tldr.sh/ |website=tldr.sh |access-date=2020-05-05 |archive-date=2020-04-27 |archive-url=https://web.archive.org/web/20200427081953/https://tldr.sh/ |url-status=live }}</ref>

In addition, some Unix [[Graphical user interface|GUI]] applications (particularly those built using the [[GNOME]] and [[KDE]] development environments) now provide end-user documentation in [[HTML]] and include embedded HTML viewers such as <code>yelp</code> for reading the help within the application. An HTML system in [[Emacs]] is also slated to replace texinfo.<ref>{{cite mailing list |title=Re: [Groff] man pages (tangential to Future Redux) |last=Raymond |first=Eric S. |author-link=Eric S. Raymond |url=https://lists.gnu.org/archive/html/groff/2014-02/msg00104.html |via=lists.gnu.org |access-date=2023-03-05 |archive-date=2023-03-05 |archive-url=https://web.archive.org/web/20230305171106/https://lists.gnu.org/archive/html/groff/2014-02/msg00104.html |url-status=live |mailing-list=groff}}</ref>