.. -*- coding: utf-8 -*- .. role:: sref(numref) .. role:: xref(numref) .. Copyright (C) 2019, Wolfgang Scherer, .. .. This file is part of Documentation Standard. .. .. Permission is granted to copy, distribute and/or modify this document .. under the terms of the GNU Free Documentation License, Version 1.3 .. or any later version published by the Free Software Foundation; .. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. .. A copy of the license is included in the section entitled "GNU .. Free Documentation License". .. inline comments (with du_comment_role) .. role:: rem(comment) .. role:: html(raw) :format: html .. role:: shx(code) :language: sh .. rst-class:: xnarrow xmedium large xhuge xultra .. _`sec:Document Snippets`: ################################################## :rem:`|||:sec:|||`\ Document Snippets ################################################## .. >>CODD See `the components of a doctoral dissertation and their order `_ .. >>CODD Dedication .. >>CODD Epigraph .. >>CODD Abstract .. compound:: Document snippets solve the problem of describing mutliple processes which consist of partial common subsets of tasks and additional unique tasks for each process. Document snippets are defined by enclosing sections in ``|<-snip->|`` tags. The document snippets are then inserted at places marked with a ``|<-snap->|`` tag. The :program:`sphinx_doc_snip.py` tool also provides replacement facilities for creating specific versions of generic documents. .. uml:: @startuml package "Common Tasks" as CT { object "Task 1" as CO1 { } object "Task 2" as CO2 { } object "Task 3" as CO3 { $ sudo passwd @user@ > @passwd@ > @passwd@ } CO1 -[hidden]> CO2 CO2 -[hidden]> CO3 } package "Process 1" as P1 { object "Task 1" as P1O1 { $ sudo passwd nu > h4t=87 > h4t=87 $ sudo chsh -s /bin/bash nu } object "Task 2" as P1O2 { } object "Task 3" as P1O3 { common task 1 } P1O1 -[hidden]> P1O2 P1O2 -[hidden]> P1O3 P1O1 --|> CO3 P1O3 --|> CO1 } package "Process 2" as P2 { object "Task 1" as P2O1 { } object "Task 2" as P2O2 { common task 1 } object "Task 3" as P2O3 { common task 2 } P2O1 -[hidden]> P2O2 P2O2 -[hidden]> P2O3 P2O2 --|> CO1 P2O3 --|> CO2 } P1 *-- CT P2 *-- CT @enduml .. \|:here:| .. >>CODD Introduction .. >>CODD Chapter ================================================== :rem:`|||:sec:|||`\ Document Snippet Definition ================================================== A document snippet is enclosed in ``|<-snip->|`` tags, which must start in column 0:: >|<-snip->| >DOCUMENT SNIPPET BODY >|<-snip->| The tags can also be commented as ``.. \|<-snip->|``:: >.. \|<-snip->| >DOCUMENT SNIPPET BODY >.. \|<-snip->| -------------------------------------------------- :rem:`||:sec:||`\ Item Prefix -------------------------------------------------- .. compound:: An item prefix is a non-empty string at the beginning of a line, consisting of - optional leading whitespace - a dash ``-``, plus ``+``, asterisks ``*``, hash dot ``#.``, integer dot ``1.``, or space ``␣`` - a minimum of 1 space ``␣``. An item prefix matches the regular expression ``(␣*([-+*␣]|(?:[#]|[0-9]+)[.])␣+)``). When a ``|<-snip->|`` tag is preceded by an item prefix the end marker is recognized at the same indentation:: > - |<-snip->| item text ... > item text ... > .. \|<-snip->| snippet title -------------------------------------------------- :rem:`||:sec:||`\ Item Prefix Snippet Examples -------------------------------------------------- :: >- |<-snip->| some item > > item body filled with stuff. > item body filled with stuff. > > .. \|<-snip->| item 1 > > * |<-snip->| some indented item > > indented item body filled with stuff. > indented item body filled with stuff. > > .. \|<-snip->| item 2 - |<-snip->| some item item body filled with stuff. item body filled with stuff. .. \|<-snip->| item 1 * |<-snip->| some indented item indented item body filled with stuff. indented item body filled with stuff. .. \|<-snip->| item 2 -------------------------------------------------- :rem:`||:sec:||`\ Document Snippet Names -------------------------------------------------- The possible names of the document snippet are derived from #. the title given after the starting or ending ``.. \|<-snip->|`` marker:: .. \|<-snip->| Most Preferred Snippet Title If the starting ``|<-snip->|`` tag has an item prefix, the title is only recognized for the end marker. #. the first section title:: .. \|<-snip->| -------------------------------------------------- :rem:`||:sec:||`\ Snippet Section Title -------------------------------------------------- .. \|<-snip->| #. the first label in the snippet body:: .. \|<-snip->| .. _`Snippet Section Title Ref`: .. \|<-snip->| The names are used in that order as title candidates for `document snippet references`_. -------------------------------------------------- :rem:`||:sec:||`\ Document Snippet Flags -------------------------------------------------- The first argument of the starting ``.. \|<-snip->|`` marker is evaluated as a string of flags consisting of: a minus sign ``-`` The snippet is removed from document body, when parsing. -------------------------------------------------- :rem:`||:sec:||`\ Document Snippet Examples -------------------------------------------------- Here is a document snippet definition named ``Snippet Section Title Ref``, with a section title of ``Snippet Section Title`` and an extra title ``Snippet Section Extra Name``: :: .. \|<-snip->| - Snippet Section Extra Name .. _`Snippet Section Title Ref`: -------------------------------------------------- :rem:`||:sec:||`\ Snippet Section Title -------------------------------------------------- section body ... .. \|<-snip->| An unlabeled document snippet with section header:: .. \|<-snip->| -------------------------------------------------- :rem:`||:sec:||`\ Unlabeled Snippet Title -------------------------------------------------- section body ... .. \|<-snip->| A named document snippet without label or section header:: .. \|<-snip->| named snippet .. \|<-snip->| .. \|<-snip->| - .. _`Snippet Tag Substitutions Label`: ================================================== :rem:`|||:sec:|||`\ Snippet Tag Substitutions ================================================== The document snippet tags ``|<-snip->|`` and ``|<-snap->|`` are defined as substitutions, which are effectively blank:: .. |<-snip->| replace:: \ :rem:`x` .. |<-snap->| replace:: \ :rem:`x` .. \|<-snip->| ================================================== :rem:`|||:sec:|||`\ Document Snippet References ================================================== A document snippet reference is recognized, when a line starts with a ``|<-snap->|`` tag:: >|<-snap->| :ref:`Snippet Tag Substitutions Label` In this case, the entire snippet definition including the section header (and section label if appropriate) are substituted for the reference line. -------------------------------------------------- :rem:`||:sec:||`\ Item Prefix Reference -------------------------------------------------- If a ``|<-snap->|`` tag is preceded by an `item prefix`_, e.g.:: >- |<-snap->| `Snippet Tag Substitutions`_ >+ |<-snap->| `Snippet Tag Substitutions`_ >* |<-snap->| :ref:`Snippet Tag Substitutions Label` >␣ |<-snap->| `Snippet Tag Substitutions`_ >1. |<-snap->| :ref:`Snippet Tag Substitutions Label` >#. |<-snap->| :ref:`Snippet Tag Substitutions Label` the snippet is inserted properly indented as item without label and section header:: - snippet body snippet body A document snippet reference is also recognized as comment:: >.. \|<-snap->| named snippet >.. - |<-snap->| named snippet >.. * |<-snap->| named snippet -------------------------------------------------- :rem:`||:sec:||`\ Item Prefix Reference Examples -------------------------------------------------- Here are some live examples from the item snippets defined above. They are actually expanded in the resolved version of this document. #. |<-snap->| item 2 #. |<-snap->| item 1 - |<-snap->| item 1 |<-snap->| item 2 -------------------------------------------------- :rem:`||:sec:||`\ Reference Features -------------------------------------------------- The tags ``|<-sn0p->|``, ``|<-sn1p->|``, ... ``|<-sn9p->|`` are equivalent to the ``|<-snap->|`` tag with the following additional features: +------+-----------------------------------------------------+ | Code | Feature | +======+=====================================================+ | 0 | remove item prefix, process as section | +------+-----------------------------------------------------+ | 1 | Bold Title | +------+-----------------------------------------------------+ | 2 | Bold Title, replace item bullet | +------+-----------------------------------------------------+ | 3 | Definition List (title = term) | +------+-----------------------------------------------------+ | 4 | Definition List (title = term), replace item bullet | +------+-----------------------------------------------------+ | 5 | Field List (title = field) | +------+-----------------------------------------------------+ | 6 | Field List (title = field), replace item bullet | +------+-----------------------------------------------------+ | 7 | undefiniert | +------+-----------------------------------------------------+ | 8 | undefiniert | +------+-----------------------------------------------------+ | 9 | undefiniert | +------+-----------------------------------------------------+ For a snippet reference with ``|<-sn1p->|`` tag:: >* |<-sn1p->| :ref:`Snippet Tag Substitutions Label` the snippet title is added as bold header:: * **Snippet Tag Defintions** snippet body snippet body With a ``|<-sn2p->|`` tag:: >* |<-sn2p->| :ref:`Snippet Tag Substitutions Label` the bullet indentation is removed and the snippet title is added as bold header:: **Snippet Tag Defintions** snippet body snippet body -------------------------------------------------- :rem:`||:sec:||`\ Reference Feature Examples -------------------------------------------------- Here are some live examples from the item snippets defined above. They are actually expanded in the resolved version of this document. - *fixed item* |<-sn1p->| item 2 ``expanded with bold title`` |<-sn2p->| item 2 ``expanded with bold title, item removed`` *Some definitions*: |<-sn3p->| item 2 |<-sn3p->| item 1 *Some fields*: |<-sn5p->| item 2 |<-sn5p->| item 1 *Itemized list expanding into various things*: - |<-sn4p->| item 2 ``expanding as definition, extended with some stuff`` - |<-sn6p->| item 2 ``expanding as field, extended with some stuff`` -------------------------------------------------- :rem:`||:sec:||`\ Reference Headers -------------------------------------------------- The tags ``|<-sn#p->|``, ``|<-sn=p->|``, ``|<-sn-p->|``, ``|<-sn~p->|``, ``|<-sn.p->|``, ``|<-sn+p->|``, are equivalent to the ``|<-snap->|`` tag, however they explicitely change the section header over-/underline. If the referenced snippet does not have a section header, it is generated from the title. -------------------------------------------------- :rem:`||:sec:||`\ Reference Examples -------------------------------------------------- In the resolved document, the following section is moved from above to here: |<-snap->| `Snippet Tag Substitutions`_ The following item, tagged with ``|<-snap->|`` is either rendered as a ReST reference in the source document or the actual document snippet is inserted *without* a section title during the document snippet resolution pass: - |<-snap->| :ref:`Snippet Tag Substitutions Label` The following item, tagged with ``|<-sn1p->|`` is either rendered as a ReST reference in the source document or the actual document snippet is inserted *with* a section title during the document snippet resolution pass: |<-sn1p->| `Snippet Tag Substitutions`_ Here comes a demoted version of the section ... |<-sn-p->| `Snippet Tag Substitutions`_ ================================================== :rem:`|||:sec:|||`\ Replacement Facilities ================================================== See section `Replacements`_ in `sphinx_doc_snip.py`_ for a details. -------------------------------------------------- :rem:`||:sec:||`\ Replacement Test -------------------------------------------------- In the resolved version, both sides will read `laptop-mb`: @hostname@ => `laptop-mb` ================================================== :rem:`|||:sec:|||`\ sphinx_doc_snip.py ================================================== .. automodule:: sphinx_doc_snip :members: .. >>CODD Conclusion .. >>CODD Appendix A .. \|:here:| .. >>CODD Notes .. ================================================== .. :rem:`|||:sec:|||`\ Footnotes .. ================================================== :html:`
` .. \[#] .. include:: doc_defs.inc .. include:: doc_defs_combined.inc .. include:: abbrev_defs.inc .. .. \||<-snap->|| doc_standalone .. include:: doc/doc_defs_secret.inc .. \||<-snap->|| doc_standalone .. \||<-snap->|| not_doc_standalone .. include:: doc_defs_secret.inc .. \||<-snap->|| not_doc_standalone .. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de