A set of utility scripts that make an effort to analysis manual pages in FreeBSD Operating System. These utilities are developed to assist in the identification of potential updates and modifications to manual pages. The utilities do not make any changes to the results, it just hihglights them.
The utilities are categorized into a few main buckets: 1. mandoc(1) - formatting style/guidance 2. Others - Anything not a style issue, missing references.
The second category is a piece meal of trial and error to see patterns. These patterns are based off analaysis of the outputs and subsequent tools that are developed to be able to determine a potential course of action.
- Lines that exceed 80 characters
- Escape sequences that are invalid
- Trailing blank references before .Fn
- Missing manual title identifiers
- Syntax error on end of sentence and no new line.
- Tab escape sequences identified
- Useless macro .Tn
- Useless macro .Ud
- Invalid paragraph macro PP after SS
- Whitespaces at end of line
- Check for no authors
The manual pages are an evolution over many decades and changes to formatting and style. The conventions listed above are a result of this evolution. There may be valid or invalid reasons for these entries and as such captured due to being identified in mandoc(1). It is important to not ignore these but to determine if this is valid for the time they were created.
The main driver of this whole process is the: run_program.sh and should be executed to be able to receive outoutput.
cd tools/
sh run_program.sh
Here is an inventory of the utilities and their purpose:
- clean_up_files.sh - Will clear out previous executions of the script
- mandoc_results.sh - Execute mandoc(1) checks
- check_pages.sh - Wrapper to parse man(1) pages
- parse_broken_refs.pl - Analysis and parse awk output from previous step
- combine_outputs.pl - An attempt to consolidate outputs
- check_whatis.pl - Execuate apropos(1) against potential issue manuals