Persistent Memory Development Kit

This is doc/README.

Subdirectories of this directory contain source for the man pages for the
Persistent Memory Development Kit in markdown format (.md files).
If you're looking for documentation to
get you started using PMDK, start here: http://pmem.io/pmdk and follow the
links to examples and man pages. Developers new to PMDK are probably looking
for libpmemobj.

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:

libpmem -- low-level persistent memory support
libpmemblk -- pmem-resident arrays of blocks
libpmemlog -- pmem-resident log files
libpmemobj -- transactional object store
libvmem -- volatile memory allocation library
libvmmalloc -- general purpose volatile memory allocation library
libpmempool -- persistent memory pool management library
pmempool -- Persistent Memory Pool Management Tool
librpmem -- remote access to persistent memory (EXPERIMENTAL)
rpmemd -- remote persistent memory daemon (EXPERIMENTAL)
daxio -- perform I/O on Device DAX device

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.