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)
--- /dev/null
+barectf.1.xml
--- /dev/null
+# 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
--- /dev/null
+[macros]
+(?su)[\\]?(?P<name>option):(?P<opt>-?-?[a-zA-Z0-9-]*)=
+(?su)[\\]?(?P<name>nloption):(?P<opt>-?-?[a-zA-Z0-9-]*)=
+:not:=not
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[option-inlinemacro]
+<literal>{opt}</literal>
+
+[nloption-inlinemacro]
+<literal>{opt}</literal>
+
+[not-inlinemacro]
+NOT
+
+[header]
+template::[header-declarations]
+<refentry>
+ <refmeta>
+ <refentrytitle>{mantitle}</refentrytitle>
+ <manvolnum>{manvolnum}</manvolnum>
+ <refmiscinfo class="source">barectf</refmiscinfo>
+ <refmiscinfo class="version">{barectf_version}</refmiscinfo>
+ <refmiscinfo class="manual">barectf manual</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+ </refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
--- /dev/null
+'\" t
+.\" Title: barectf
+.\" Author: [see the "AUTHORS" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\" 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 <http://diamon.org/ctf> packets natively, out of a YAML configuration input file \fICONFIG\fR\&. The full documentation of barectf is available on the project\(cqs website <http://barectf.org>\&.
+.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 <https://github.com/efficios/barectf/issues>\&.
+.SH "RESOURCES"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Project\(cqs website <http://barectf.org>
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Continuous integration <http://ci.lttng.org/job/barectf>
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Mailing list <http://lists.lttng.org>
+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 <irc://irc.oftc.net/lttng>:
+\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 <mailto:pproulx@efficios.com>\&.
+.sp
+barectf is distributed under the MIT License <https://github.com/efficios/barectf/blob/master/LICENSE>\&.
+.SH "AUTHORS"
+.sp
+barectf was originally written by and is maintained by, as of this version, Philippe Proulx <mailto:pproulx@efficios.com>\&. Other, nice people have since contributed to the project\&.
+.sp
+barectf is supported by EfficiOS <http://www.efficios.com/>\&.
--- /dev/null
+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].
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:template match="literal">
+ <xsl:text>\fB</xsl:text>
+ <xsl:value-of select="." />
+ <xsl:text>\fR</xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:template match="co">
+ <xsl:value-of select="concat('\','fB(',substring-after(@id,'-'),')','\','fR')"/>
+ </xsl:template>
+ <xsl:template match="calloutlist">
+ <xsl:value-of select="."/>
+ <xsl:text>sp </xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text> </xsl:text>
+ </xsl:template>
+ <xsl:template match="callout">
+ <xsl:value-of select="concat('\','fB',substring-after(@arearefs,'-'),'. ','\','fR')"/>
+ <xsl:apply-templates/>
+ <xsl:value-of select="."/>
+ <xsl:text>br </xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:template match="ulink">
+ <xsl:apply-templates/><xsl:text> <</xsl:text><xsl:value-of select="@url"/><xsl:text>></xsl:text>
+ </xsl:template>
+ <xsl:template match="link">
+ <xsl:text>\fI</xsl:text><xsl:apply-templates/><xsl:text>\fR</xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:import href="manpage-callouts.xsl" />
+ <xsl:import href="manpage-bold-literal.xsl" />
+ <xsl:import href="manpage-links.xsl" />
+
+ <!-- disable end notes -->
+ <xsl:param name="man.endnotes.are.numbered">0</xsl:param>
+</xsl:stylesheet>
projects / barectf.git / commitdiff
