From: Philippe Proulx Date: Wed, 30 Mar 2016 21:30:39 +0000 (-0400) Subject: Add barectf(1) man page X-Git-Url: http://drtracing.org/?a=commitdiff_plain;h=b4d4665f0bfa1b2c0e43640c369fb8649ecf6ea0;p=deliverable%2Fbarectf.git Add barectf(1) man page Signed-off-by: Philippe Proulx --- diff --git a/README.md b/README.md index 29d07a9..c67516e 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,22 @@ With [Homebrew](http://brew.sh/): pip3 install barectf +### Man page + +Since the philosphy of setuptools packages is to include everything +within the package, the barectf man page is not installed on the system +when installing barectf with `pip` or with `setup.py`. This would be the +job of distribution packages. + +You can install it manually: + + wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1 + +Replace `VERSION` with the desired version, for example: + + wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1 + + ## What is CTF? See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell) diff --git a/doc/man/.gitignore b/doc/man/.gitignore new file mode 100644 index 0000000..def272c --- /dev/null +++ b/doc/man/.gitignore @@ -0,0 +1 @@ +barectf.1.xml diff --git a/doc/man/Makefile b/doc/man/Makefile new file mode 100644 index 0000000..207fea2 --- /dev/null +++ b/doc/man/Makefile @@ -0,0 +1,35 @@ +# source +SRC = barectf + +# config +ASCIIDOC_CONF = asciidoc.conf +XSL_FILES = \ + manpage.xsl \ + manpage-callouts.xsl \ + manpage-bold-literal.xsl \ + manpage-links.xsl +XSL_SRC_FILES = $(addprefix xsl/,$(XSL_FILES)) + +# tools +ASCIIDOC ?= asciidoc +XMLTO ?= xmlto +ADOC = $(ASCIIDOC) -f $(ASCIIDOC_CONF) -d manpage \ + -a barectf_version=$(shell grep '^__version__' ../../barectf/__init__.py | grep -Po '\d+\.\d+\.\d+(?:-\w+)?') +ADOC_DOCBOOK = $(ADOC) -b docbook +XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man + +# recipes +.PHONY: all + +all: $(SRC).1 + +$(SRC).1.xml: $(SRC).1.txt $(ASCIIDOC_CONF) + $(ADOC_DOCBOOK) -o $@ $< + +$(SRC).1: $(SRC).1.xml $(XSL_SRC_FILES) + $(XTO) $< + +.PHONY: clean + +clean: + rm -f $(SRC).1 $(SRC).1.xml diff --git a/doc/man/asciidoc.conf b/doc/man/asciidoc.conf new file mode 100644 index 0000000..8960c96 --- /dev/null +++ b/doc/man/asciidoc.conf @@ -0,0 +1,32 @@ +[macros] +(?su)[\\]?(?Poption):(?P-?-?[a-zA-Z0-9-]*)= +(?su)[\\]?(?Pnloption):(?P-?-?[a-zA-Z0-9-]*)= +:not:=not + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[option-inlinemacro] +{opt} + +[nloption-inlinemacro] +{opt} + +[not-inlinemacro] +NOT + +[header] +template::[header-declarations] + + + {mantitle} + {manvolnum} + barectf + {barectf_version} + barectf manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] diff --git a/doc/man/barectf.1 b/doc/man/barectf.1 new file mode 100644 index 0000000..7cf6289 --- /dev/null +++ b/doc/man/barectf.1 @@ -0,0 +1,185 @@ +'\" t +.\" Title: barectf +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 03/30/2016 +.\" Manual: barectf manual +.\" Source: barectf 2.1.3 +.\" Language: English +.\" +.TH "BARECTF" "1" "03/30/2016" "barectf 2\&.1\&.3" "barectf manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +barectf \- Generate C99 code that can write native CTF packets +.SH "SYNOPSIS" +.sp +.nf +\fBbarectf\fR [\fB--prefix\fR=\fIPREFIX\fR] [\fB--dump-config\fR] + [\fB--code-dir\fR=\fIPATH\fR] [\fB--headers-dir\fR=\fIPATH\fR] [\fB--metadata-dir\fR=\fIPATH\fR] + [\fB-I\fR \fIPATH\fR]\&... [\fB--ignore-include-not-found\fR] \fICONFIG\fR +.fi +.SH "DESCRIPTION" +.sp +The \fBbarectf\fR command generates C99 code, that itself can write Common Trace Format packets natively, out of a YAML configuration input file \fICONFIG\fR\&. The full documentation of barectf is available on the project\(cqs website \&. +.sp +A prefix is used to scope the generated file names, as well as the generated function names, macro names, structure names, and so on\&. By default, this prefix is \fBbarectf_\fR\&. It can be overridden by the configuration file, and ultimately by the \fB--prefix\fR option\&. +.sp +By default, all generated C and CTF metadata files are written to the current working directory\&. The \fB--code-dir\fR, \fB--headers-dir\fR, and \fB--metadata-dir\fR options are used to control where the generated files should go\&. +.sp +You can add directories to be searched into for inclusion files, before the default search directories, by using the \fB-I\fR option one or more times\&. +.sp +By default, if an inclusion file is not found while processing the configuration file \fICONFIG\fR, an error is emitted\&. You can instruct \fBbarectf\fR to continue silently instead by providing the \fB--ignore-include-not-found\fR option\&. +.sp +To view the effective YAML configuration file used for generating the C and CTF metadata files, after having processed all inclusion files, use the \fB--dump-config\fR option\&. +.SH "OPTIONS" +.PP +\fB-c\fR, \fB--code-dir\fR=\fIPATH\fR +.RS 4 +Write C source files to directory +\fIPATH\fR +instead of the current working directory\&. +.RE +.PP +\fB--dump-config\fR +.RS 4 +Dump the effective YAML configuration file, after all inclusions are processed, to the standard output\&. +.RE +.PP +\fB-H\fR, \fB--headers-dir\fR=\fIPATH\fR +.RS 4 +Write C header files to directory +\fIPATH\fR +instead of the current working directory\&. +.RE +.PP +\fB--ignore-include-not-found\fR +.RS 4 +Do not consider as an error inclusion files that are not found: continue silently\&. +.RE +.PP +\fB-I\fR, \fB--include-dir\fR=\fIPATH\fR +.RS 4 +Prepend +\fIPATH\fR +to the list of directories to search into for include files\&. The default list of directories is the current working directory, followed by the directory containing the provided, "standard" inclusion files\&. +.RE +.PP +\fB-m\fR, \fB--metadata-dir\fR=\fIPATH\fR +.RS 4 +Write CTF metadata file to directory +\fIPATH\fR +instead of the current working directory\&. +.RE +.PP +\fB-p\fR, \fB--prefix\fR=\fIPREFIX\fR +.RS 4 +Override the configuration file\(cqs prefix with +\fIPREFIX\fR\&. This prefix is used in file names, function names, macro names, structure names, and the rest\&. When not specified in the configuration file, the default prefix is +\fBbarectf_\fR\&. +.RE +.PP +\fB-h\fR, \fB--help\fR +.RS 4 +Show command help\&. +.RE +.PP +\fB--version\fR +.RS 4 +Show the command\(cqs version\&. +.RE +.SH "EXIT STATUS" +.PP +\fB0\fR +.RS 4 +Success +.RE +.PP +\fBNot 0\fR +.RS 4 +Error +.RE +.SH "BUGS" +.sp +Please report any bug or usability issue as a GitHub issue \&. +.SH "RESOURCES" +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Project\(cqs website +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Continuous integration +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Mailing list +for support and development: +\fBlttng-dev@lists.lttng.org\fR +(prefix the subject message with +\fB[barectf]\fR) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +IRC channel : +\fB#lttng\fR +on +\fBirc.oftc.net\fR +(\fBeepp\fR +is barectf\(cqs author and maintainer) +.RE +.SH "COPYRIGHT" +.sp +Copyright (c) 2014\-2016 Philippe Proulx \&. +.sp +barectf is distributed under the MIT License \&. +.SH "AUTHORS" +.sp +barectf was originally written by and is maintained by, as of this version, Philippe Proulx \&. Other, nice people have since contributed to the project\&. +.sp +barectf is supported by EfficiOS \&. diff --git a/doc/man/barectf.1.txt b/doc/man/barectf.1.txt new file mode 100644 index 0000000..bfda04b --- /dev/null +++ b/doc/man/barectf.1.txt @@ -0,0 +1,130 @@ +barectf(1) +========== + + +NAME +---- +barectf - Generate C99 code that can write native CTF packets + + +SYNOPSIS +-------- +[verse] +*barectf* [option:--prefix='PREFIX'] [option:--dump-config] + [option:--code-dir='PATH'] [option:--headers-dir='PATH'] [option:--metadata-dir='PATH'] + [option:-I 'PATH']... [option:--ignore-include-not-found] 'CONFIG' + + +DESCRIPTION +----------- +The `barectf` command generates C99 code, that itself can write +http://diamon.org/ctf[Common Trace Format] packets natively, out of a +YAML configuration input file 'CONFIG'. The full documentation of +barectf is available on the http://barectf.org[project's website]. + +A prefix is used to scope the generated file names, as well as the +generated function names, macro names, structure names, and so on. +By default, this prefix is `barectf_`. It can be overridden by the +configuration file, and ultimately by the option:--prefix option. + +By default, all generated C and CTF metadata files are written to the +current working directory. The option:--code-dir, option:--headers-dir, +and option:--metadata-dir options are used to control where the +generated files should go. + +You can add directories to be searched into for inclusion files, before +the default search directories, by using the option:-I option one or +more times. + +By default, if an inclusion file is not found while processing the +configuration file 'CONFIG', an error is emitted. You can instruct +`barectf` to continue silently instead by providing the +option:--ignore-include-not-found option. + +To view the effective YAML configuration file used for generating the +C and CTF metadata files, after having processed all inclusion files, +use the option:--dump-config option. + + +OPTIONS +------- +option:-c, option:--code-dir='PATH':: + Write C source files to directory 'PATH' instead of the current + working directory. + +option:--dump-config:: + Dump the effective YAML configuration file, after all inclusions are + processed, to the standard output. + +option:-H, option:--headers-dir='PATH':: + Write C header files to directory 'PATH' instead of the current + working directory. + +option:--ignore-include-not-found:: + Do not consider as an error inclusion files that are not found: + continue silently. + +option:-I, option:--include-dir='PATH':: + Prepend 'PATH' to the list of directories to search into for include + files. The default list of directories is the current working + directory, followed by the directory containing the provided, + "standard" inclusion files. + +option:-m, option:--metadata-dir='PATH':: + Write CTF metadata file to directory 'PATH' instead of the current + working directory. + +option:-p, option:--prefix='PREFIX':: + Override the configuration file's prefix with 'PREFIX'. This prefix + is used in file names, function names, macro names, structure names, + and the rest. When not specified in the configuration file, the + default prefix is `barectf_`. + +option:-h, option:--help:: + Show command help. + +option:--version:: + Show the command's version. + + +EXIT STATUS +----------- +*0*:: + Success + +*Not 0*:: + Error + + +BUGS +---- +Please report any bug or usability issue as a +https://github.com/efficios/barectf/issues[GitHub issue]. + + +RESOURCES +--------- +* http://barectf.org[Project's website] +* http://ci.lttng.org/job/barectf[Continuous integration] +* http://lists.lttng.org[Mailing list] for support and + development: `lttng-dev@lists.lttng.org` (prefix the subject message + with `[barectf]`) +* irc://irc.oftc.net/lttng[IRC channel]: `#lttng` on `irc.oftc.net` + (`eepp` is barectf's author and maintainer) + + +COPYRIGHT +--------- +Copyright (c) 2014-2016 mailto:pproulx@efficios.com[Philippe Proulx]. + +barectf is distributed under the +https://github.com/efficios/barectf/blob/master/LICENSE[MIT License]. + + +AUTHORS +------- +barectf was originally written by and is maintained by, as of this +version, mailto:pproulx@efficios.com[Philippe Proulx]. Other, nice +people have since contributed to the project. + +barectf is supported by http://www.efficios.com/[EfficiOS]. diff --git a/doc/man/xsl/manpage-bold-literal.xsl b/doc/man/xsl/manpage-bold-literal.xsl new file mode 100644 index 0000000..c0e0900 --- /dev/null +++ b/doc/man/xsl/manpage-bold-literal.xsl @@ -0,0 +1,7 @@ + + + \fB + + \fR + + diff --git a/doc/man/xsl/manpage-callouts.xsl b/doc/man/xsl/manpage-callouts.xsl new file mode 100644 index 0000000..2f7a5d7 --- /dev/null +++ b/doc/man/xsl/manpage-callouts.xsl @@ -0,0 +1,17 @@ + + + + + + + sp + + + + + + + + br + + diff --git a/doc/man/xsl/manpage-links.xsl b/doc/man/xsl/manpage-links.xsl new file mode 100644 index 0000000..0662921 --- /dev/null +++ b/doc/man/xsl/manpage-links.xsl @@ -0,0 +1,8 @@ + + + <> + + + \fI\fR + + diff --git a/doc/man/xsl/manpage.xsl b/doc/man/xsl/manpage.xsl new file mode 100644 index 0000000..b51049f --- /dev/null +++ b/doc/man/xsl/manpage.xsl @@ -0,0 +1,8 @@ + + + + + + + 0 +