THINGS TO CONSIDER WHEN WRITING VARNISH RST DOCUMENTATION

Inline Markup

Please try to be consistent with inline markup and fix places which do not follow the style:

VCL language and other literals as literal
placeholders and emphasis as emphasis
no interpreted text except where it actually is that

.. _Reference: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#character-level-inline-markup

exception: Links to manpages outside varnish as man(section)
use code blocks for::

Examples and

other code

References are tricky

To build html documentation, we want to create cross-document cross-references using::

:ref:reference name

Trouble is that rst2man and rst2pdf working on individual files cannot parse ref roles to anything outside the current rst file, so we need to differentiate link targets depending on the kind of documentation:

set link targets on the top of documents ending up in man-pages following the manpage naming scheme, e.g.::

.. _varnishd(1):
set link targets for important paragraphs following the scheme ref-doc-section, for instance::

.. _ref-varnishd-opt_T:

These can be referenced from other documents making up the html documentation, but not from stand-alone documents (like man-pages).
in all documents which are used to create man-pages, add the following definition at the top::

.. role:: ref(emphasis)

This will allow the use of ref in a compatible manner, IF references follow the man-page naming scheme
to be compatible both with sphinx and rst2man, use implicit link targets_ in stand-alone documents, like this one creating References are tricky_::

References are tricky_

.. _implicit link targets: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets

Document Structure

While RST supports a great deal of flexibility for adornments of titles and section headers, we should adhere to a consistent style to avoid breaking the document structure unintentionally.

Within the Varnish-Cache project, we should use these characters:

Over and underline = for document titles
Over and underline - for document subtitles
Underline = for sections
Underline - for subsection
Underline ~ for subsubsections

This is in line with the example in https://docutils.sourceforge.io/docs/user/rst/quickstart.html#sections

HISTORY

This README was initially started by Nils Goroll.

COPYRIGHT

This document is licensed under the same licence as Varnish itself. See LICENCE for details.