Commit a8088cdc authored by Antoine Beaupré's avatar Antoine Beaupré

rework README to split acks and installations and remove empty section

parent 408c1b42
......@@ -12,9 +12,6 @@ This suite of tools is designed to run on `manpages.debian.org
.. split
Example
-------
You can do a test run of this software against your local APT cache,
like this::
......@@ -39,13 +36,13 @@ above test. The warnings can be safely ignored. ``debmans`` doesn't
normally require ``dpkg-dev`` in operation if you use a properly
configured mirror.
Common tasks
------------
Examples
--------
A more normal run would be to run on a regular mirror. This will extract
all manpages from the given mirror and convert to HTML::
debmans --mirror /srv/mirror --output static extract render
debmans --mirror /srv/mirror --output html/ extract render
This can be ran repeatedly and only extracted manpages will be rendered.
......@@ -81,17 +78,17 @@ Rendering the pages can be done separately with::
This is especially important if the extraction process was interrupted,
as only part of the manpages will be rendered on subsequent runs.
Manpages are currently rendered with
`man2html <http://users.actrix.gen.nz/michael/vhman2html.html>`__ but
this can be changed with the ``-r`` flag, although no other renderer has
been tested and the output may not be compatible with ``man2html``.
Manpages are rendered using the plugin defined by the ``--plugin``
argument. Arbitrary plugin can be loaded provided that they comply
with the :class:`debmans.renderer.ManpageRenderer` and
:class:`debmans.renderer.CommandRenderer` public APIs.
Static pages rendering
~~~~~~~~~~~~~~~~~~~~~~
The templating engine is fairly simple, based on Jinja2, which uses
standard ``{{foo}}`` placeholders. The template is in
``static/template.html`` and should be following debian.org's graphic
``debmans/templates/template.html`` and should be following debian.org's graphic
design conventions.
This should generate the markdown files::
......@@ -101,7 +98,7 @@ This should generate the markdown files::
Use ``--prefix`` if the directory is not at the root of the host.
Installation
------------
============
``debmans`` can be installed through pip with::
......@@ -127,8 +124,10 @@ It can also be ran from the source tree directly with::
The dependencies are listed in the ``setup.py`` file.
.. split-acknowledgements
Acknowledgements
----------------
================
``debmans`` was written by Antoine Beaupré and is licensed under the
Affero GPLv3, see :doc:`license` for the complete license.
......
......@@ -2,3 +2,6 @@ License
=======
.. include:: ../LICENSE.rst
.. include:: ../README.rst
:start-after: .. split-acknowledgements
......@@ -3,3 +3,4 @@ Usage
.. include:: ../README.rst
:start-after: .. split
:end-before: .. split-acknowledgements
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment