This is doc/README.

Subdirectories of this directory contain source for the man pages for vmem
and vmmalloc in markdown format (.md files).

To generate web-based documentation or Linux/FreeBSD man pages, you need to
have groff and pandoc installed. m4 macros are used in the document
sources to generate OS-specific variants of man pages and web-based
documentation. The macros are defined in macros.man. Processing is performed
by the ../utils/md2man.sh script.

All files in the *generated* directory are automatically generated and updated
by the pmdk-bot. **DO NOT MODIFY THE FILES IN THAT DIRECTORY**. All changes to
the documentation must be made by modifying the *.md files in the following
document subdirectories:

libvmem -- volatile memory allocation library
libvmmalloc -- general purpose volatile memory allocation library

These man pages provide the API specification for the corresponding libraries
and commands in this source tree, so any updates to one should be tested,
reviewed, and committed with changes to the other.

To create more readable text files from the source, use:
	$ [g]make

NOTE: This will write man page output into the *generated* subdirectory. Files
in this directory MUST NOT be included in any pull requests.

The man(1) command may be used to format generated man pages for viewing
in a terminal window (includes bold, underline, etc.), for example:
	$ man generated/libpmem.7
	$ man generated/pmemobj_create.3

In addition, for testing purposes ../utils/md2man.sh will generate a
preprocessed markdown file with the headers stripped off if the TESTOPTS
variable is set. For example:

	$ export TESTOPTS="-DWIN32 -UFREEBSD -UWEB"
	$ ../utils/md2man.sh libpmemobj/libpmemobj.7.md x libpmemobj.7.win.md

will generate a version of the libpmemobj.7 man page for Windows in markdown
format. The resulting file may be viewed with a markdown-enabled browser.
