Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IGOR(1)			FreeBSD	General	Commands Manual		       IGOR(1)

NAME
     igor -- automated proofreading for	documentation files

SYNOPSIS
     igor -h
     igor [-abcdefilmnoprstuvwxyzDERSWXZ] [-C linerange] [-L linelen] [-V VID]
	  [file	...]

DESCRIPTION
     igor proofreads documentation files to detect problems.  The goal is to
     make formatting and problem detection easier, allowing the	writer to con-
     centrate on the content.

     Some tests	can be performed on all	files, while others are	specific to
     mdoc(7) or	DocBook	files.	igor uses file(1) to detect a file's type and
     only runs the applicable tests on it.

     Files compressed with gzip(1) or bzip(2) are automatically	decompressed.
     If	multiple files are specified, filenames	are displayed before each is
     analyzed.	If no files are	given, input is	read from stdin.

     By	default, all tests are performed.  If options for individual tests are
     given, only those tests will be done.  Several shortcut options make
     testing common combinations easier; see the SHORTCUT OPTIONS section be-
     low.

HELP OPTIONS
     -h	       Show a usage summary and	exit.

DISPLAY	FORMAT OPTIONS
     -R	       Produce output with ANSI	color highlighting, to be used with
	       the -R option of	less(1).  If -R	is not given, "[" and "]" are
	       used to mark problem areas.

     -C	linerange
	       Restrict	output to a range of lines from	the file being
	       checked.	 Some tests process the	entire file and	will be
	       silently	skipped	when -C	is used.  linerange consists of	start
	       and end line numbers separated by a colon or dash.  Start or
	       end may be omitted:

	       -C 1000-2000  Show problems on lines 1000 to 2000 of the	file.

	       -C 1000:	     Show problems from	line 1000 on.

	       -C -2000	     Show problems up to line 2000.

     -v	       Be verbose with diagnostic and status messages.

     -V	VID    Limit output to a specific VuXML	vulnerability VID, or use the
	       literal keyword "latest"	to specify the most recent (first
	       listed) vulnerability in	the VuXML file.

     -X	       Produce Checkstyle XML output.  This overrides -R.

SHORTCUT OPTIONS
     -D	       Do all mdoc(7) tests but	ignore the document date (.Dd).	 Use
	       this option to skip needless warnings about the document	date
	       while a man page	is being revised.  When	ready for the actual
	       commit, run igor	without	this option to check the date.	Equiv-
	       alent to	-abefmrsuw.

     -z	       Run all applicable non-whitespace (content) tests on a docu-
	       ment.  Use this test to find content problems that will require
	       retranslation of	a document.

     -Z	       Run all applicable whitespace tests on a	document.  Use this to
	       find whitespace-only problems that can be fixed without requir-
	       ing retranslation of a document.

TESTS FOR ALL FILE TYPES
     -a	     Verify proper usage of abbreviations like "e.g." and "i.e.".

     -b	     Check for usage of	bad phrases like "equally as" and some unfor-
	     tunate contractions like "gzip'd" (the preferred form is
	     "gzipped" for ASCII or mdoc(7), or	"<command>gzip</command>ped"
	     for DocBook.)

     -f	     Check for mentions	of obsolete FreeBSD features like "cvsup".

     -r	     Check for repeated	words like "is is" or "and and".

     -s	     Detect spelling errors.  This test	looks for known	misspellings
	     found in existing FreeBSD documents.  Additional files of mis-
	     spelled words may be added	with the IGORSPELLFILES	environment
	     variable, or placed in the	/usr/local/etc/igor/spelling direc-
	     tory.  The	first word on each line, including apostrophes,	will
	     be	included in the	list of	known misspellings to be checked.
	     Blank lines and lines starting with a # character are ignored.
	     The Debian	project	has a list of words at
	     http://anonscm.debian.org/gitweb/?p=lintian/lintian.git;a=blob_plain;f=vendors/debian/ftp-master-auto-reject/data/spelling/corrections;hb=HEAD

     -u	     Identify contractions, which make translation more	difficult.

     -w	     Find general whitespace errors, including trailing	whitespace at
	     the end of	lines, blank lines containing whitespace, and tabs
	     following a space.

     -y	     Analyze and report	on the writing style used in the document.
	     This test is off by default.

TESTS FOR MDOC(7) FILES
     -d	     Check whether document date (.Dd) has been	set to today's date,
	     as	it should be when there	have been nontrivial changes to	a man
	     page.  (See the -D	option below.)

     -e	     Verify that sentences start on a new line.	 mdoc(7) does not en-
	     force this, it is a style issue.

     -g	     Look for duplicated external references in	the SEE	ALSO section
	     of	a man page.

     -m	     Check for minimal mdoc(7) document	structure.

     -p	     Check for mdoc(7) whitespace style, like no blank lines.

     -x	     Check for the existence of	external references (.Xr).  Due	to a
	     tendency for false	positives with these tests, they are off by
	     default.

TESTS FOR DOCBOOK FILES
     -c	     Check title capitalization	against	AP style rules.	 Portions of
	     titles wrapped in tags like <filename> are	ignored.

     -i	     Check indentation.

     -l	     Check for long lines.  The	default	line length is 70 characters,
	     the recommended value from	the FDP	Primer (see SEE	ALSO below).
	     The line length value may be overridden with -L linelen.

     -n	     Verify that sentences start with two spaces.

     -o	     Verify that open and close	tags like <para> and </para> occur in
	     matching pairs.

     -t	     Check for tag usage style problems, like using <programlisting>
	     inside a <para>.

     -E	     Check for DocBook writing style problems, including redundant use
	     of	markup and text	like

		   Edit	the <filename>/etc/rc.conf</filename> file.

	     This can be expressed less	redundantly as

		   Edit	<filename>/etc/rc.conf</filename>.

     -L	     Set the preferred line length (see	-l above.)

     -S	     Check for "straggler" tags	that are on the	next line when they
	     should be up against the content preceding	them, or undesired
	     whitespace	before or after	the content.  Although this is white-
	     space, it is content, too.	 Any change of these spaces inside one
	     of	these tags is a	content	change that should also	be changed in
	     translations.  Because of that, the straggler test	is part	of the
	     content tests run with -z rather than the whitespace tests.

     -W	     Test for DocBook-specific whitespace problems, including multi-
	     ples of eight spaces at the start of a line which should be re-
	     placed with tabs, tabs hidden inside text,	and odd	numbers	of
	     spaces used for indentation.

ENVIRONMENT
     IGORSPELLFILES  A list of whitespace-delimited filenames containing addi-
		     tional misspelled words.

FILES
     /usr/local/etc/igor/spelling/  Directory for additional misspelled	word
				    files.

EXAMPLES
     Check gpart.8.gz for all errors, showing them with	ANSI highlights.

	   igor	-R gpart.8.gz |	less -R	-S

     Check tuning.7.gz for all mdoc(7) errors except document date (.Dt), then
     show a writing style analysis.

	   igor	-R -D -y /usr/share/man/man7/tuning.7.gz | less	-RS

     Check a file from stdin, showing messages in plain	text.

	   cat README |	igor -R

     Check a DocBook file for non-whitespace (content) errors.

	   igor	-Rz chapter.xml	| less -RS

     Check the same DocBook file for only whitespace errors.

	   igor	-RZ chapter.xml	| less -RS

     Check a file for all errors found on lines	829 through 1488.

	   igor	-R -C 829:1488 chapter.xml | less -RS

     Check all the English DocBook files.

	   igor	-R `find /usr/doc/en_US.ISO8859-1/ -name "*.xml"` | less -RS

     Check all the man pages in	a directory, ignoring the document date.

	   igor	-RD /usr/share/man/man8/* | less -RS

SEE ALSO
     The FreeBSD Documentation Project Primer for New Contributors
     http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/

AUTHORS
     Warren Block <wblock@FreeBSD.org>

FreeBSD	13.0		       September 2, 2015		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | HELP OPTIONS | DISPLAY FORMAT OPTIONS | SHORTCUT OPTIONS | TESTS FOR ALL FILE TYPES | TESTS FOR MDOC(7) FILES | TESTS FOR DOCBOOK FILES | ENVIRONMENT | FILES | EXAMPLES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=igor&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help