.. -*- coding: utf-8 -*- .. role:: sref(numref) .. role:: xref(numref) .. Copyright (C) 2019, Dominik Appold, .. .. 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 .. _line_diversion: #################################################### :rem:`|||:sec:|||`\ UML annotations - line_diversion #################################################### .. >>CODD See `the components of a doctoral dissertation and their order `_ .. >>CODD Dedication .. >>CODD Epigraph .. >>CODD Abstract .. compound:: The python module :mod:`line_diversion` extracts marked annotation lines from text files. The extraction result is generally a `PlantUML`_ diagram. Future extensions to extract other material (e.g. :program:`dot`\ (1) graphs) are possible and probable. While writing source code, the `PlantUML`_ annotations can be easily added near the source code lines. (See section `Emacs support`_). The idea of this concept is to minimize the distance between source code and documentation (see |chapter-relevance|)\ [#]_. .. \|:here:| .. >>CODD Introduction .. >>CODD Chapter ================================================== :rem:`|||:sec:|||`\ Emacs support ================================================== A set of Emacs commands facilitates code annotation, reformatting of annotations and diagram preview. The commands are all prefixed with `umlx-` and bound with the prefix command :kbd:`C-# u`. See :kbd:`C-# u C-h` for key bindings:: C-# u a umlx-mark-activity C-# u b umlx-re-mark-buffer C-# u c umlx-convert-old C-# u g umlx-grep-find C-# u k umlx-unmark C-# u m umlx-mark C-# u o umlx-occur C-# u t umlx-symbol-tag-delimiter C-# u u umlx-re-mark C-# u x umlx-extract In addtion to the :kbd:`C-# u ` binding, some commands are also directly bound to :kbd:`C-# `:: C-# C-a umlx-mark-activity C-# C-b umlx-re-mark-buffer C-# C-k umlx-unmark C-# RET umlx-mark C-# C-t umlx-symbol-tag-delimiter C-# C-u umlx-re-mark .. note:: If :kbd:`C-#` does not work (e.g. in a terminal), the prefix command :kbd:`C-c #` can be used instead. ====================================================== :rem:`|||:sec:|||`\ Annotation tags and markers ====================================================== An annotation marker consists of - an annotation tag, which consists of - a comment start sequence, - followed directly (without whitespace) by a tag symbol, which consists of - a line_diversion type - and a diagram number, - optional type parameters, - optional text - and an optional comment end sequence. ANNOTATION-MARKER:: [ TYPE-PARAMETERS ..] [ ] [[] ] ANNOTATION-TAG:: ANNOTATION-TAG-SYMBOL:: E.g.:: #a55 a #a55 :; b #a55 :; #red #a55 ' (yes) An annotated line is defined as:: [[] ] | [] | :[;] -------------------------------------------------- :rem:`||:sec:||`\ Comment start regular expression -------------------------------------------------- The regular expression for matching a comment start is defined in module :mod:`line_diversion`:: COMMENT_TYPE_RX='(?://+|/\\*+|;+|@:u?[bl]?comm_?@|--|