From c2d024f47ec8cac823f38a65091f1be34d6b5d53 Mon Sep 17 00:00:00 2001 From: Jim Evins Date: Sat, 29 Dec 2018 14:10:04 -0500 Subject: [PATCH] Added manpages for glabels-qt and glabels-batch-qt. --- .gitignore | 3 + CMakeLists.txt | 1 + docs/README.md | 4 + user-docs/CMakeLists.txt | 34 +++++ user-docs/_build/man/glabels-batch-qt.1 | 121 +++++++++++++++++ user-docs/_build/man/glabels-qt.1 | 80 +++++++++++ user-docs/conf.py | 169 ++++++++++++++++++++++++ user-docs/index.rst | 9 ++ user-docs/man/glabels-batch-qt.rst | 88 ++++++++++++ user-docs/man/glabels-qt.rst | 52 ++++++++ user-docs/man/index.rst | 10 ++ 11 files changed, 571 insertions(+) create mode 100644 docs/README.md create mode 100644 user-docs/CMakeLists.txt create mode 100644 user-docs/_build/man/glabels-batch-qt.1 create mode 100644 user-docs/_build/man/glabels-qt.1 create mode 100644 user-docs/conf.py create mode 100644 user-docs/index.rst create mode 100644 user-docs/man/glabels-batch-qt.rst create mode 100644 user-docs/man/glabels-qt.rst create mode 100644 user-docs/man/index.rst diff --git a/.gitignore b/.gitignore index cfadfca..f512be1 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,9 @@ *.la *.a +# Sphinx-build artifacts +/user-docs/_build/doctrees + # # Ignore artifacts from editors, patching, etc. # diff --git a/CMakeLists.txt b/CMakeLists.txt index 67b6729..2df148a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -136,6 +136,7 @@ add_subdirectory (model) add_subdirectory (glabels) add_subdirectory (glabels-batch) add_subdirectory (templates) +add_subdirectory (user-docs) add_subdirectory (translations) add_subdirectory (data) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7d0aa0d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,4 @@ +Developer Documentation Directory +================================= + +This directory contains developer documentation. For user documentation, see [user-docs/](../user-docs). diff --git a/user-docs/CMakeLists.txt b/user-docs/CMakeLists.txt new file mode 100644 index 0000000..330b1a6 --- /dev/null +++ b/user-docs/CMakeLists.txt @@ -0,0 +1,34 @@ +add_custom_target (user-docs DEPENDS manpages) + +set (man_sources + man/glabels-qt.rst + man/glabels-batch-qt.rst +) + +#======================================= +# Rebuild man pages +#======================================= +foreach (_man_source ${man_sources}) + string (REGEX REPLACE "([^.]*)\.rst" "_build/\\1.1" _man_page ${_man_source}) + list (APPEND man_pages ${_man_page}) +endforeach () + +add_custom_command ( + OUTPUT ${man_pages} + COMMAND sphinx-build -M man ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/_build + COMMENT "Generating man pages." + DEPENDS ${man_sources} +) + +add_custom_target (manpages DEPENDS ${man_pages}) + +#======================================= +# Rebuild user manual +#======================================= +# TODO + +#======================================= +# Install +#======================================= +install (FILES ${man_pages} DESTINATION share/man/man1) + diff --git a/user-docs/_build/man/glabels-batch-qt.1 b/user-docs/_build/man/glabels-batch-qt.1 new file mode 100644 index 0000000..6fa48b5 --- /dev/null +++ b/user-docs/_build/man/glabels-batch-qt.1 @@ -0,0 +1,121 @@ +.\" Man page generated from reStructuredText. +. +.TH "GLABELS-BATCH-QT" "1" "Dec 29, 2018" "" "gLabels" +.SH NAME +glabels-batch-qt \- gLabels Documentation +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBglabels\-batch\-qt\fP [\fIoptions\fP] [\fIfilename\fP] +.SH DESCRIPTION +.sp +\fBglabels\-batch\-qt\fP is a utility for printing files previously +prepared with \fBglabels\-qt\fP from the command line. It is suitable +for use with scripts. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-h, \-\-help +Displays usage information and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v, \-\-version +Displays version information and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p , \-\-printer +Send output to . +.UNINDENT +.INDENT 0.0 +.TP +.B \-o , \-\-output +Set output filename to . Set to "\-" for stdout. +(Default="output.pdf") +.UNINDENT +.INDENT 0.0 +.TP +.B \-s , \-\-sheets +Set number of sheets to . (Default=1) +.UNINDENT +.INDENT 0.0 +.TP +.B \-c , \-\-copies +Set number of copies to . (Default=1) +.UNINDENT +.INDENT 0.0 +.TP +.B \-f , \-\-first +Set starting label on 1st page to . (Default=1) +.UNINDENT +.INDENT 0.0 +.TP +.B \-l, \-\-outlines +Print label outlines. +.UNINDENT +.INDENT 0.0 +.TP +.B \-m, \-\-crop\-marks +Print crop marks. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r, \-\-reverse +Print in reverse (mirror image). +.UNINDENT +.SH FILES +.INDENT 0.0 +.TP +.B ${prefix}/share/glabels\-qt/templates/ +Directory containing predefined product templates distributed with glabels. +.UNINDENT +.INDENT 0.0 +.TP +.B ${XDG_CONFIG_HOME}/glabels.org/glabels\-qt/ +Directory containing user defined product templates created with the +gLabels Product Template Designer. \fBDo not place manually created +templates here!\fP +.UNINDENT +.INDENT 0.0 +.TP +.B ${HOME}/.glabels/ +Directory for manually created product templates. +.UNINDENT +.SH SEE ALSO +.sp +\fBglabels\-qt(1)\fP +.sp +The gLabels homepage at <\fI\%http://glabels.org/\fP>. +.SH AUTHOR +Jim Evins +.SH COPYRIGHT +2018, Jim Evins +.\" Generated by docutils manpage writer. +. diff --git a/user-docs/_build/man/glabels-qt.1 b/user-docs/_build/man/glabels-qt.1 new file mode 100644 index 0000000..66bd854 --- /dev/null +++ b/user-docs/_build/man/glabels-qt.1 @@ -0,0 +1,80 @@ +.\" Man page generated from reStructuredText. +. +.TH "GLABELS-QT" "1" "Dec 29, 2018" "" "gLabels" +.SH NAME +glabels-qt \- gLabels Documentation +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBglabels\-qt\fP [\fIoptions\fP] [\fIfilename\fP ...] +.SH DESCRIPTION +.sp +\fBglabels\-qt\fP is a GUI program for designing and printing labels and +business cards. It is designed to work with various laser/ink\-jet peel\-off +label and business card sheets that you’ll find at most office supply stores. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-h, \-\-help +Displays usage information and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v, \-\-version +Displays version information and exits. +.UNINDENT +.SH FILES +.INDENT 0.0 +.TP +.B ${prefix}/share/glabels\-qt/templates/ +Directory containing predefined product templates distributed with glabels. +.UNINDENT +.INDENT 0.0 +.TP +.B ${XDG_CONFIG_HOME}/glabels.org/glabels\-qt/ +Directory containing user defined product templates created with the +gLabels Product Template Designer. \fBDo not place manually created +templates here!\fP +.UNINDENT +.INDENT 0.0 +.TP +.B ${HOME}/.glabels/ +Directory for manually created product templates. +.UNINDENT +.SH SEE ALSO +.sp +\fBglabels\-batch\-qt(1)\fP +.sp +The gLabels homepage at <\fI\%http://glabels.org/\fP>. +.SH AUTHOR +Jim Evins +.SH COPYRIGHT +2018, Jim Evins +.\" Generated by docutils manpage writer. +. diff --git a/user-docs/conf.py b/user-docs/conf.py new file mode 100644 index 0000000..9535f1f --- /dev/null +++ b/user-docs/conf.py @@ -0,0 +1,169 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# gLabels documentation build configuration file, created by +# sphinx-quickstart on Sat Dec 29 09:07:11 2018. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = [] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'gLabels' +copyright = '2018, Jim Evins ' +author = 'Jim Evins' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '' +# The full version, including alpha/beta/rc tags. +release = '' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'gLabelsdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'gLabels.tex', 'gLabels Documentation', + 'Jim Evins', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('man/glabels-qt', 'glabels-qt', 'gLabels Documentation', [author], 1), + ('man/glabels-batch-qt', 'glabels-batch-qt', 'gLabels Documentation', [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'gLabels', 'gLabels Documentation', + author, 'gLabels', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/user-docs/index.rst b/user-docs/index.rst new file mode 100644 index 0000000..024f542 --- /dev/null +++ b/user-docs/index.rst @@ -0,0 +1,9 @@ +gLabels User Manual +=================== + +.. toctree:: + :maxdepth: 2 + + man/index + + diff --git a/user-docs/man/glabels-batch-qt.rst b/user-docs/man/glabels-batch-qt.rst new file mode 100644 index 0000000..0ad6fdd --- /dev/null +++ b/user-docs/man/glabels-batch-qt.rst @@ -0,0 +1,88 @@ +glabels-batch-qt +================ + +SYNOPSIS +-------- + +**glabels-batch-qt** [*options*] [*filename*] + +DESCRIPTION +----------- + +:program:`glabels-batch-qt` is a utility for printing files previously +prepared with :program:`glabels-qt` from the command line. It is suitable +for use with scripts. + + +OPTIONS +------- + +.. program:: glabels-batch-qt + +.. option:: -h, --help + + Displays usage information and exits. + +.. option:: -v, --version + + Displays version information and exits. + +.. program:: glabels-batch-qt + +.. option:: -p , --printer + + Send output to . + +.. option:: -o , --output + + Set output filename to . Set to "-" for stdout. + (Default="output.pdf") + +.. option:: -s , --sheets + + Set number of sheets to . (Default=1) + +.. option:: -c , --copies + + Set number of copies to . (Default=1) + +.. option:: -f , --first + + Set starting label on 1st page to . (Default=1) + +.. option:: -l, --outlines + + Print label outlines. + +.. option:: -m, --crop-marks + + Print crop marks. + +.. option:: -r, --reverse + + Print in reverse (mirror image). + +FILES +----- + +.. describe:: ${prefix}/share/glabels-qt/templates/ + + Directory containing predefined product templates distributed with glabels. + +.. describe:: ${XDG_CONFIG_HOME}/glabels.org/glabels-qt/ + + Directory containing user defined product templates created with the + gLabels Product Template Designer. **Do not place manually created + templates here!** + +.. describe:: ${HOME}/.glabels/ + + Directory for manually created product templates. + + +SEE ALSO +-------- + +:manpage:`glabels-qt(1)` + +The gLabels homepage at . diff --git a/user-docs/man/glabels-qt.rst b/user-docs/man/glabels-qt.rst new file mode 100644 index 0000000..1c2b152 --- /dev/null +++ b/user-docs/man/glabels-qt.rst @@ -0,0 +1,52 @@ +glabels-qt +========== + +SYNOPSIS +-------- + +**glabels-qt** [*options*] [*filename* ...] + +DESCRIPTION +----------- + +:program:`glabels-qt` is a GUI program for designing and printing labels and +business cards. It is designed to work with various laser/ink-jet peel-off +label and business card sheets that you’ll find at most office supply stores. + +OPTIONS +------- + +.. program:: glabels-qt + +.. option:: -h, --help + + Displays usage information and exits. + +.. option:: -v, --version + + Displays version information and exits. + +FILES +----- + +.. describe:: ${prefix}/share/glabels-qt/templates/ + + Directory containing predefined product templates distributed with glabels. + +.. describe:: ${XDG_CONFIG_HOME}/glabels.org/glabels-qt/ + + Directory containing user defined product templates created with the + gLabels Product Template Designer. **Do not place manually created + templates here!** + +.. describe:: ${HOME}/.glabels/ + + Directory for manually created product templates. + + +SEE ALSO +-------- + +:manpage:`glabels-batch-qt(1)` + +The gLabels homepage at . diff --git a/user-docs/man/index.rst b/user-docs/man/index.rst new file mode 100644 index 0000000..f5fccbe --- /dev/null +++ b/user-docs/man/index.rst @@ -0,0 +1,10 @@ +gLabels Manpages +================ + +.. toctree:: + :maxdepth: 1 + + glabels-qt + glabels-batch-qt + +