DocManager

Name

docmanager — DocManager is a tool to manage meta-information within DocBook 5 documents.

Synopsis

docmanager [GLOBAL OPTIONS] [SUBCOMMAND] [OPTIONS] {FILES...}

Description

DocManager is a tool to manage meta-information within DocBook 5 documents. You can add, delete, edit, and query meta information. Each meta-information is stored in the info in the DocManager namespace.

The following example shows an XML file after being edited with DocManager:

<info>
 <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
  <dm:test1>value1</dm:property>
  <dm:test2>value2</dm:maintainer>
 </dm:docmanager>
</info>

In this example, we used these commands:

$ docmanager set -p test1=value1 example.xml

$ docmanager set -p test2=value2 example.xml

Global Options

-h or --help: Show a help dialog. You can also use -h with subcommands to get help about a specific subcommand. Example: docmanager set -h
-v: Be more verbose. The verbosity level can be increased by adding more "v" behind the option. (Example: -vv and so on. Maximum: -vvv)
--version: Display the version of DocManager.
--langlist: Displays a list with all supported language codes.

Commands

init `[OPTIONS]` `FILES`

Initializes an XML document with all relevant properties. Property is the name of an XML tag.

--maintainer MAINTAINER

Set the maintainer for the given XML files.

Set the status for the given XML files.

--deadline YYYY-MM-DD

Set the deadline for the given XML files.

--priority 1-10

Set the priority for the given XML files.

--translation [yes|no]

Set the translation element for the given XML files. than -p

--languages LANGUAGE_CODE

Set the languages for the given XML files. You can get a list of language codes if you call docmanager --langlist

--release RELEASE

Set the release type (Example: SUSE Linux Enterprise Server 12) for the given XML files.

--repository URL

Set the repository URL (maybe a GitHub URL?) for this document.

--with-bugtracker

Adds a bugtracker structure to an XML file.

--bugtracker-url URL

Sets the bugtracker URL. (Works for Bugzilla and GitHub)

For Bugzilla, for example: https://bugzilla.suse.com/enter_bug.cgi

For GitHub, for example: https://github.com/openSUSE/suse-xsl/issues/new (Please let the URL point to the "new issue" site of your documentation repository - otherwise, it will not work)

--bugtracker-component COMPONENT

Sets the bugtracker component. Example: Documentation (Only available for Bugzilla)

--bugtracker-product PRODUCT

Sets the bugtracker product. Example: SUSE Cloud 4 (Only available for Bugzilla)

--bugtracker-assignee ASSIGNEE

Sets the assignee either for GitHub or Bugzilla. Example: the login name of the user like "mschnitzer"

--bugtracker-version VERSION

Sets the version of the product release. Example: Beta 3 (The version is the milestone on GitHub)

--stop-on-error

If this option is given, DocManager will stop if there is an XML error in one file.

--force

This option forces the initialization.

set `[OPTIONS]` `FILES`

Setting one or more properties.

-p PROPERTY=VALUE

Set the value of a property. Property is the name of the XML tag. For example: "-p property=value" would result in <dm:property>value</dm:property>

It's possible to use sub properties. For example: "-p property1/property2/property3=value" would result in:

<dm:property1>
 <dm:property2>
  <dm:property3>value</dm:property3>
 </dm:property2>
</dm:property1>

--stop-on-error

In case of errors in the XML files, this option exits the script without writing any changes. If not specified, files causing errors will be reported and otherwise be ignored.

--maintainer MAINTAINER

Set the maintainer for the given XML files. Note: If you use -p maintainer=FOO, --maintainer has a higher priority than -p

Set the status for the given XML files. Note: If you use -p status=FOO, --status has a higher priority than -p

--deadline YYYY-MM-DD

Set the deadline for the given XML files. Note: If you use -p deadline=FOO, --deadline has a higher priority than -p

--priority 1-10

Set the priority for the given XML files. Note: If you use -p priority=FOO, --priority has a higher priority than -p

--translation [yes|no]

Set the translation element for the given XML files. Note: If you use -p translation=FOO, --translation has a higher priority than -p

--languages LANGUAGE_CODE

Set the languages for the given XML files. You can get a list of language codes if you call docmanager --langlist Note: If you use -p languages=FOO, --languages has a higher priority than -p

--release RELEASE

Set the release type (Example: SUSE Linux Enterprise Server 12) for the given XML files. Note: If you use -p release=FOO, --release has a higher priority than -p

--repository URL

Set the repository URL (maybe a GitHub URL?) for this document. Note: If you use -p repository=FOO, --repository has a higher priority than -p

--bugtracker-url URL

Sets the bugtracker URL. (Works for Bugzilla and GitHub)

For Bugzilla, for example: https://bugzilla.suse.com/enter_bug.cgi

For GitHub, for example: https://github.com/openSUSE/suse-xsl/issues/new (Please let the URL point to the "new issue" site of your documentation repository - otherwise, it will not work)

--bugtracker-component COMPONENT

Sets the bugtracker component. Example: Documentation (Only available for Bugzilla)

--bugtracker-product PRODUCT

Sets the bugtracker product. Example: SUSE Cloud 4 (Only available for Bugzilla)

--bugtracker-assignee ASSIGNEE

Sets the assignee either for GitHub or Bugzilla. Example: the login name of the user like "mschnitzer"

--bugtracker-version VERSION

Sets the version of the product release. Example: Beta 3 (The version is the milestone on GitHub)

get `[OPTIONS]` `FILES`

Getting one or more property values.

-p PROPERTY

Gets the value of a property.

It is possible to access sub properties with a / between each property. For example: "property1/property2/property3" would try to access the value "foo" in the following schema:

<dm:property1>
 <dm:property2>
  <dm:property3>foo</dm:property3>
 </dm:property2>
</dm:property1>

--format FORMAT

Set the output format. Valid format types: table, json, xml

del `[OPTIONS]` `FILES`

Deleting one or more existing properties.

-p PROPERTY: Delete a property in all given XML files. Note: You can build conditions with "=" like: del -p property=value - This means, DocManager will only delete the properties in the given XML files if they have the value set to "value".

analyze `[OPTIONS]` `FILES`

Analyzes one or more DocBook 5 files.

--queryformat/-qf QUERY_FORMAT_STRING

The query format string is used for the output of each analyzed file.

$ docmanager analyze -qf "Hi {maintainer}" example1.xml example2.xml

{maintainer} is a placeholder for the <maintainer> property. The example above prints two outputs: The first is for example1.xml and the second for example2.xml. If in example1.xml the <maintainer> property is set to mschnitzer and in example2.xml <maintainer> is set (for example) to toms, the output would be:

Hi mschnitzer
Hi toms

There are also pre defined placeholders:

{os.file}: Will be replaced with the current file name.

--filter/-f FILTER

The filter option allows you to reduce your data to specific properties. For example:

+maintainer=mschnitzer
-maintainer=toms
maintainer=mschnitzer

You might wonder why we don't used an operator in example three. If no or an invalid operator is set, DocManager will use by default the + operator.

Operator definitions:

+: The property must have that content.
-: The property must not have that content.

--sort/-s PROPERTY

Sorts the output of your analyzed data by a property. You can also specifiy filename as sort method. The output will be then sorted by the name of your files.

--default-output/-do VALUE

This option specifies the default output value for properties, which are empty or not set.

config `OPTION(--system|--user|--repo|--own)` `PROPERTY` `VALUE`

Manage the configuration files.

--system/-s: Uses the system configuration file from /etc/docmanager/docmanager.conf. If the file was not found, DocManager will create that file.
--user/-u: Uses the user configuration file from /home/{user}/.config/docmanager/docmanager.conf. If the file was not found, DocManager will create that file.
--repo/-r: Uses the git repository configuration file from {current_git_director}/.git/docmanager/docmanager.conf. If the file was not found, DocManager will create that file.
--own/-o FILE: Uses an own configuration file. If the file was not found, DocManager will create that file.
PROPERTY: The property of the configuration file. You have to separate the section from the property with a dot. For example: section.property
VALUE: The value of the property.

alias `[-h] (-s|-u|-r|-o_FILE) ACTION ALIAS [COMMAND]`

Tool for modifying aliases.

--help/-h

Shows the help page.

CONFIG_FILE

--system/-s: This option let the alias feature use the system configuration file from /etc
--system/-s: This option let the alias feature use the system configuration file from /etc
--user/-u: This option let the alias feature use the user configuration file from /home/{user}/.config/docmanager
--repo/-r: This option let the alias feature use the repository configuration file from the current git repository. The user has to be in a git repository otherwise it won't work.
--own/-o FILE: This option let the alias feature use an own configuration file.

ACTION (set|get|del)

The action method for the alias command.

ALIAS

The name of the alias.

COMMAND

The command which has to be executed.

Examples:

get -p maintainer example.xml
set --maintainer mschnitzer example.xml
analyze -qf "{maintainer}" -f "maintainer=mschnitzer" *

Configuration Files

The following configuration files are searched (in this order, from lowest to highest):

/etc/docmanager/docmanager.conf: System-wide configuration file
$XDG_CONFIG_HOME/docmanager/docmanager.conf: User-specific configuration file. If $XDG_CONFIG_HOME is not set or empty, $HOME/.config/docmanager/docmanager.conf will be used.
$REPO_DIR/.git/docmanager.conf: Repository-specific configuration file.

If no --config option was given, DocManager will read all of these files that are available in the listed order above. Files which are not available will be ignored.

The files are read in the order given above, with last value found taking precedence over values read earlier.

Syntax

The DocManager configuration file uses the INI format, for example:

[general]
# General options, used for all subcommands
foo=bar

The general section contains an entry with the name foo and its value bar.

Section and Variable Names

Note that this list is non-comprehensive and not necessarily complete. The following sections can be set:

general

Relevant settings for all sub commands.

verbosity_level

Sets the default verbosity level.

0: Show only WARNINGS, ERRORS, and CRITICAL messages.
1: Show only INFOS, WARNINGS, ERRORS, and CRITICAL messages.
2: Shows everything.

analyze

Controls several options for the analzye feature and contains the following variables:

queryformat: Defines the standard query format when the user didn't use one with -qf.

alias

Aliases (shortcuts) for several commands. This is currently work in progress!

Exit Codes

0: Everything went fine.
1: A file could not be found.
2: Could not set the given value for a property.
3: Error during parsing an XML file.
4: Invalid usage of key=value in --set
5: (For development only): Method "..." is not implemented.
6: The info element could not be found in one of the given XML files.
7: DocManager was called without any arguments.
8: One of the given XML documents is not valid.
9: The format for the given option of the set subcommand is not correct. (Wrong usage of --status for example: docmanager set --status bla example.xml)
10: File permission error. (For example: Could not write into the given XML file)
11: The given XML document is not a DocBook 5 document. The start tag has to be in the official DocBook 5 namespace.
12: This error code appears only when the 'set' sub command and the if --stop-on-error were not used. If there are errors in at least one of the given XML files, the error code will be returned at the end of the process. This does not mean that files are unchanged, only that the invalid XML files remain untouched.
13: Invalid syntax in at least one analyze filter. A filter has the following syntax: [OPERATOR][PROPERTY]=[CONDITION] - Read the help text for the --filter/-f option for more information about filters.
14: One property name in either --sort or --filter is not a valid XML property. (Syntax Error)
15: The syntax of the configuration property is wrong. (Example for a correct syntax: section.property)
16: No method was specified. Use either --system, --user, --repo, or --repo.
17: User interrupted program by pressing Ctrl+ C
18: The given file is a directory.

Examples

docmanager set -p hello=world example.xml: Set the information value "world" in the property "hello".
docmanager set --maintainer mschnitzer example.xml: Set the maintainer element in the example.xml file to "mschnitzer".
docmanager get -p hello example.xml: Reads the value of the property "hello". If you followed the first example, the output would be "hello=world".
docmanager get -p hello example.xml --format json: Reads the value of the property "hello". The output format is JSON.
docmanager get -p hello example.xml --format table: Reads the value of the property "hello". The output will be shown as table.
docmanager del -p hello example.xml: Deletes the "hello" in example.xml.
docmanager -vv set --maintainer mschnitzer example.xml: Increase the "verbosity level" for the "set" command. You can increase the "verbosity level" if you add more "v" behind the dash.