Man Page Generation
From PAPIDocs
Jump to: navigation, search

This page contains information on how to generate man pages from the PAPI wiki man pages.

Wiki Format Restrictions

There are some restrictions on what kinds of wiki syntax is allowed. Some of these restrictions could be lifted upon further development of the converter tool.

  • Nowhere it is possible to embed different font style within each other. For example you cannot start bold text, then make it italic (to make a bold italic text) instead you must end the bold style and begin with the italic/bold style.
  • All headings (signified by the = character) of any level (1 to n) will become level 1 headings in the resulting man page (since there is no notion of heading levels in troff/man)
  • All tables must have no extra modifying parameters to them (such a collspacing, line spacing). Their row and columns must also have no extra tags to them.
  • Each row of a table must be on its own line (between two newline characters).
  • Any pre-formated text must use the <pre> tag. Any other way will not convert.
  • The name of a wiki page that is to be converted to a man page must have a period followed by a number 1-8 so that the mediawiki->man converter knows which section it belongs to.
  • Only bulleted wiki lists are supported. It is unknown what happens when dealing with multi-level lists.
    • Within lists the first dash (-) is interpreted as the separator between the term and the description of it.
  • Syntax Color Highlighting - lang and line parameters only recongized

How to Convert

Below is a list of steps that will produce the man pages.

  1. Obtain a list of all the pages you want to convert to man format, such as the list for PAPI Classic Man Pages or the PAPI Component Man Pages
  2. Paste the list in the Special:Export page. You will be prompted for saving a file. This file contains all the wiki pages in xml format. Making sure to choose only the most recent versions of the wiki page will reduce the file size and the time and system resources needed to parse the file.
  3. Use the mediawiki2man.php script to extract the man files. You can specify which folder to use for output (the default folder name is "out" and will be created if it can). It is also possible to specify a date to only generate man files that have been changed since then. For a list of options invoke mediawiki2man.php without any arguments (e.g. php mediawiki2man.php).
  4. After the generation is complete the folder will contains 8 folders which correspond to the 8 different man sections.