Author: aconway
Date: Wed Jan 21 20:43:08 2015
New Revision: 1653646
URL: http://svn.apache.org/r1653646
Log:
NO-JIRA: Expanded READMEs under doc/ to help developers update the docs.
Added:
qpid/dispatch/trunk/doc/api/README
qpid/dispatch/trunk/doc/book/README
Modified:
qpid/dispatch/trunk/README
qpid/dispatch/trunk/doc/README
qpid/dispatch/trunk/doc/man/README
qpid/dispatch/trunk/doc/man/qdmanage.8.noopt.md.in
Modified: qpid/dispatch/trunk/README
URL:
http://svn.apache.org/viewvc/qpid/dispatch/trunk/README?rev=1653646&r1=1653645&r2=1653646&view=diff
==============================================================================
--- qpid/dispatch/trunk/README (original)
+++ qpid/dispatch/trunk/README Wed Jan 21 20:43:08 2015
@@ -19,9 +19,7 @@ packages installed:
Dispatch will not build on Windows.
-To build formatted documentation (man pages, HTML, PDF) you will need
-- pandoc (1.12 or later) for HTML and man pages.
-- pdflatex (3.1 or later) for PDF (available via pandoc-pdf on yum based
systems)
+To build formatted documentation (man pages, HTML, PDF) see the requirements
in doc/README
Building and testing
====================
Modified: qpid/dispatch/trunk/doc/README
URL:
http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/README?rev=1653646&r1=1653645&r2=1653646&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/README (original)
+++ qpid/dispatch/trunk/doc/README Wed Jan 21 20:43:08 2015
@@ -1,29 +1,70 @@
-<!--*-markdown-*-->
+<!--*-markdown-*-
-# Documentation for dispatch
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+nspecific language governing permissions and limitations
+under the License.
+
+-->
+
+# Building documentation
+
+You can disable building documentation entirely with:
+
+ cmake -DBUILD_DOCS=OFF
+
+By default it is enabled automatically if you have the required tools. For a
yum
+based system you can install these packages:
+
+- pandoc (1.12) for HTML book and man pages.
+- pandoc-pdf (1.12) for `pdflatex` program needed to build PDF version of the
book.
+- doxygen (1.8) for API documentation.
+- graphviz (2.34) for `dot` program needed to include diagrams in API
documentation.
+
+The versions above are known to work, earlier versions may or may not. If you
+find an earlier version does work please update this README.
+
+If you have a subset of these tools, you will get a subset of the output.
+
+You can enable/disable specific tools with these cmake options:
+ USE_PANDOC, USE_PDFLATEX, USE_DOXYGEN, USE_DOT.
+
+
+# Writing documentation
Documentation is written in [markdown][] format with [pandoc][] extensions. We
use [pandoc][] to generate formatted documentation such as man pages, HTML and
PDF.
-All markdown, HTML and PDF documentation is installed in the share/doc
-directory. Man pages are also installed in the standard share/man location.
-
-The [dispatch web site](http://qpid.apache.org/components/dispatch-router) has
-documentation for each release.
+[markdown]: http://daringfireball.net/projects/markdown/syntax "Markdown
syntax"
-Sub-directories:
+[pandoc]: http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
"Pandoc markdown syntax"
-`book/`: Book-format documentation.
+All documentation is installed in the share/doc directory. Man pages are also
+installed in the standard share/man/man* locations.
-`man/`: Unix man pages.
+The [dispatch web site](http://qpid.apache.org/components/dispatch-router) has
+pre-generated documentation for each release and a random snapshot of the
trunk.
-`api/`: Generated API documentation.
+Sub-directories (each has a README with more specifics):
-`notes/`: Developer notes: project information, design notes, or anything else
+- `book/`: Book-format documentation.
+- `man/`: Unix man pages.
+- `api/`: Generated API documentation.
+- `notes/`: Developer notes: project information, design notes, or anything
else
that's primarily of developer interest. These are not installed.
-[markdown]: http://daringfireball.net/projects/markdown/syntax "Markdown
syntax"
-[pandoc]: http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
"Pandoc markdown syntax"
Added: qpid/dispatch/trunk/doc/api/README
URL:
http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/api/README?rev=1653646&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/api/README (added)
+++ qpid/dispatch/trunk/doc/api/README Wed Jan 21 20:43:08 2015
@@ -0,0 +1,33 @@
+<!--*-markdown-*-
+
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+nspecific language governing permissions and limitations
+under the License.
+
+-->
+
+# API documentation
+
+`api`: User API documentation is generated automatically from
[doxygen](http://www.doxygen.org)
+comments in public header files. You can use the `@internal` tag to mark items
+that should be hidden in the user API docs.
+
+`api_dev` includes everything in `api`, plus anything marked `@internal`, plus
+doc comments from private headers and implementation files in the `src`
+directory. It is a cheap-and-cheerful code-browser for developers.
+
+Please include doc comments for everything in public header files. Use your
+discretion as to when it is useful in private implementation files.
Added: qpid/dispatch/trunk/doc/book/README
URL:
http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/README?rev=1653646&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/README (added)
+++ qpid/dispatch/trunk/doc/book/README Wed Jan 21 20:43:08 2015
@@ -0,0 +1,40 @@
+<!-*-markdown-*-
+
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+nspecific language governing permissions and limitations
+under the License.
+
+-->
+
+# Editing the book.
+
+Most chapters of the book are simply [markdown][] files. Edit the chapter file
+to edit the book.
+
+[markdown]: http://daringfireball.net/projects/markdown/syntax "Markdown
syntax"
+
+The chapters are listed in the variable BOOK in CMakeLists.txt, update that
variable if
+you add or re-order chapters.
+
+Some chapters are generated by python scripts rather than being simple source
+files. For example `schema.md` is generated by `schema_md.py` from the
+documentation strings in the management schema `qdrouterd.json`.
+
+It is *much* better to capture external documentation automatically than to
+cut/paste or re-type it into the book. Duplicated information becomes
+inconsistent almost immediately. The initial effort will be repaid manyfold.
+
+
Modified: qpid/dispatch/trunk/doc/man/README
URL:
http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/README?rev=1653646&r1=1653645&r2=1653646&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/man/README (original)
+++ qpid/dispatch/trunk/doc/man/README Wed Jan 21 20:43:08 2015
@@ -1,4 +1,4 @@
-<!-*-markdown-*-
+<!--*-markdown-*-
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -21,59 +21,44 @@ under the License.
# How man pages are generated.
-Man pages are generated from markdown sources.
+Man pages are generated by combining markdown sources and the `--help` option
of
+command line tools.
-Command line tools --help option provides a very brief usage and list of
-options. Man pages should be more detailed, but we do not want to repeat the
-option information from --help as it will easily become out of date.
+The `--help` option should give a *very brief* usage message and list of
+options. Man pages should give much more detailed information about use, but
we
+do not want to duplicate the `--help` information as it will easily become out
+of date.
-A small python script helt2md.py combines the manpage markdown source named
-*.noopt.md with the output of "program --help" into a single markdown file.
+The markdown source file for the man page is called something like
`foo.1.noopt.md.in`. This gets
+transformed as follows:
-The final man page is generated from the markdown by pandoc.
+- Substitute cmake variables of the form `${X}`. (`foo.1.noopt.md`)
+- Replace the *Options* section with the output of `program --help`.
(`foo.1.md`)
+- Convert to nroff-format man page by pandoc. (`foo.1`)
+# Rules for markdown map pages
-# A really quick guide to nroff and man-page macros
+Use markdown top-level headings `# Heading` with the standard man page section
+names: *Name*, *Synopsis*, *Description*, *Options*, *Files*, *See also*
-## The title heading
+Use markdown sub-headings`## Sub Heading` for sub-sections
- .TH <name> <section>
- .TH somefile.conf 5
- .TH somedaemon 8
+Include an *Options* section like this (it will be replaced with the real
options from `--help`):
-## Section headings
+ # Options
- .SH <text>
- .SH OPTIONS
- .SH "SOMETHING ELSE"
+ Run `qdmanage --help` to see options.
-## Subsection headings
+Use the pandoc definition list markdown extension for named items. Here's an
example:
- .SS <text>
+ `create` [*ATTR=VALUE*...]
+ : Create a new entity with the specified attributes.
+ With the --stdin option, read attributes from stdin. This can be a JSON
+ map of attributes to create a single entity, or a JSON list of maps to
create multiple entitiees.
-## Indented paragraphs for named items
+ `read`
+ : Print the attributes of an entity specified by the --name or
--identity options.
+ With the --stdin option, create entities based on data from stdin.
This can be a JSON
+ map of attributes to create a single entity, or a JSON list of maps to
create multiple entitiees.
- .IP <item-name>
- <item-text>
-
-## Paragraph breaks
-
- .P
-
-## Bold and italic
-
- .B "some bold text"
- .I "some italic text"
- Some \fBbold text\fP
- Some \fIitalic text\fP
-
-## Things to keep in mind
-
- - Arguments containing spaces must be quoted: "some arg"
- - Dot macros must start on their own line
-
-## More information
-
- - http://linux.die.net/man/7/man-pages
- - http://linux.die.net/man/7/man
- - http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html
+Most other markdown markup will do what you expect, e.g. *emphasis*,
**strong**, `code` etc.
Modified: qpid/dispatch/trunk/doc/man/qdmanage.8.noopt.md.in
URL:
http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/man/qdmanage.8.noopt.md.in?rev=1653646&r1=1653645&r2=1653646&view=diff
==============================================================================
--- qpid/dispatch/trunk/doc/man/qdmanage.8.noopt.md.in (original)
+++ qpid/dispatch/trunk/doc/man/qdmanage.8.noopt.md.in Wed Jan 21 20:43:08 2015
@@ -16,8 +16,8 @@ with qdrouter.
# Operations
`query` [*ATTR*...]
-: Prints the named attributes of all entities. With no arguments prints all
attributes.
- The --type option restricts the result to entities extending the type.
+: Print the attributes named in the ATTR list or all attributes if none are
listed.
+ Print attributes for all entities by default, use --type, --name and
--identity options to restrict what is printed.
`create` [*ATTR=VALUE*...]
: Create a new entity with the specified attributes.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
