[CRIU] [PATCH] docs: Rework the manual

[Christopher Covington]

On 05/01/2015 07:22 AM, Cyrill Gorcunov wrote:
> I think this might be more readable if we group options
> by the commands. So here is the result. Please read and
> tell me what you think.
> 
> I put formatted manual here because read diff itself
> is almost impossible.
> 
>  | CRIU(8)                           CRIU Manual                          CRIU(8)
>  |
>  |
>  |
>  | NAME
>  |        criu - checkpoint/restore in userspace
>  |
>  | SYNOPSIS
>  |        criu command [options]

The git man page puts command between angle brackets: "<command>".

>  | DESCRIPTION
>  |        criu is a command line utility to steer checkpoint and restore
>  |        procedures.

I find this to be vague. I would say something like (adapted from the wiki page):

criu is a command line utility for checkpointing and restoring running
applications. It does this by saving their state to disk as a collection of
files (see the dump command) and creating equivalent processes from those
files (see the restore command). The restore operation can be performed at a
later time, on a different system, or both.

>  |        cpuinfo check
>  |            Reads information about CPU from an image file and checks if it is
>  |            compatible with currently running CPU.

This has been copied down to the commands section and should be deleted.

>  | OPTIONS
>  |        The options are depending on the command criu run with.
>  |
>  |    Common options
>  |        Common options are applied to any command.
>  |
>  |        -v[num|v...]
>  |            Set logging level to num. The higer the level, the more output is
>  |            produced. Either numeric values or multiple v can be used. The
>  |            following levels are available:
>  |
>  |            ·   -v1, -v only messages and errors;
>  |
>  |            ·   -v2, -vv also warnings (default level);
>  |
>  |            ·   -v3, -vvv also information messages and timestamps;
>  |
>  |            ·   -v4, -vvvv lots of debug.
>  |
>  |        --pidfile file
>  |            Write root task, service or page-server pid into a file.
>  |
>  |        -o, --log-file file
>  |            Write logging messages to file.
>  |
>  |        --log-pid
>  |            Write separate logging files per each pid.
>  |
>  |        -D, --images-dir path
>  |            Use path path as a base directory where to look for dump files set.
>  |
>  |        --prev-images-dir path
>  |            Use path path as a parent directory where to look for dump files
>  |            set. This make sence in case of increment dumps.
>  |
>  |        -W, --work-dir dir
>  |            Use directory dir for putting logs, pidfiles and statistics. If not
>  |            specified, path from -D option is taken.
>  |
>  |        --close fd
>  |            Close file with descriptor fd before any actions.
>  |
>  |        -L, --libdir path
>  |            Path to a plugins directory.
>  |
>  |        --action-script SCRIPT
>  |            Add an external action script. The environment variable
>  |            CRTOOLS_SCRIPT_ACTION contains one of the actions:
>  |
>  |            ·   post-dump run an action upon dump completion;
>  |
>  |            ·   post-restore run an action upon restore completion;
>  |
>  |            ·   network-lock lock network in a target network namespace;
>  |
>  |            ·   network-unlock unlock network in a target network namespace;
>  |
>  |            ·   setup-namespaces run an action once root task just been created
>  |                with required namespaces, note it is early stage on restore
>  |                nothing were restored yet except namespaces themselves.
>  |
>  |        -V, --version
>  |            Print program version and exit.
>  |
>  |        -h, --help
>  |            Print inline help and exit.

I think there should be a commands header here.

>  |    pre-dump
>  |        Launches that named pre-dump procedure, where criu does snapshot of
>  |        memory changes since previous pre-dump. Also criu forms fsnotify cache
>  |        which speedup restore procedure. pre-dump requires at least -t option
>  |        (see dump below). Optionally page-server options may be specified.
>  |
>  |        --track-mem
>  |            Turn on memory changes tracker in the kernel. If the option is not
>  |            passed the memory tracker get turned on implicitly.

Chris

-- 
Qualcomm Innovation Center, Inc.
The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
a Linux Foundation Collaborative Project