HTTPS SSH

Techgdoc: technical documentation done right

Techgdoc is a set of scripts and macros that help to create, modify and track technical documents. Its main feature are

  • Uses LaTeX (actually XeLaTeX) to generate PDF technical documents
  • Keeps track of changes using Mercurial
  • Tagged Mercurial changesets translate to named revisions of the PDF output
  • A revision history sheet with Mercurial tags and log messages can be incorporated into the document
  • Technical fields (e.g. author, document number, project, etc.) can be the PDF output as M4 macro expansions in the LaTeX source
  • Mercurial changeset hashes (and commit authors) are also defined as M4 macros so any final PDF can be tracked back to the source tree
  • Fancy cover sheets can be designed as SVG drawings, which can in turn contain M4 macros (even Mercurial changeset hashes)
  • The differences between any two commits may be explicitly shown in an annotated PDF output
  • Many authors may contribute by cloning, branching and mergin Mercurial repositories

Techgdoc is part of the wasora suite.

Quick start

  1. Make sure you have installed

    a. Bash b. M4 c. Mercurial d. XeLaTeX e. Inkscape

    Also, the bibliography manager Biber will be needed is references are to be included in the document. A proper apt-get call that should work in Debian-based GNU/Linux distributions is:

    # apt-get install bash m4 mercurial texlive-xetex \
      texlive-latex-recommended inkscape biber
    
  2. Clone the techgdoc repository into the directory that will hold the document sources:

    $ hg clone https://bitbucket.org/wasora/techgdoc document
    $ cd document
    
  3. Make a new branch within the working tree:

    $ hg branch document
    marked working directory as branch document
    (branches are permanent and global, did you want a bookmark?)
    

    The branch name is irrelevant, but this step is needed to tell techgdoc that the generic template was instantiated as a particular document and any further change is made to the document and not to the template.

    And no, we did not want a bookmark.

  4. Edit the file fields.m4 and fill in the required fields, namely

    • title
    • type
    • docnumber (or name)
    • class (should be a valid LaTeX class)
    • mainlanguage (should be a valid babel language)

    Other optional fields may be also defined (remember to remove the dnl macro from the beginning of the line).

  5. Edit the file body.tex and write the first draft of your masterpiece.

  6. Commit the changes in the newly-created branch:

    $ hg commit
    

    If Mercurial complains about you not supplying a username, just edit either .hg/hgrc (repository settings) or ~/.hgrc (user settings) and add the following lines:

    [ui]
    username = John Doe <john@mail.com>
    

    A sample template is automatically provided by Mercurial by calling

    $ hg config --edit
    

    Note that this source is where techgdoc reads the information about the document author.

  7. Run the techgdoc.sh script to generate the DRAFT version of the document.

    $ ./techgdoc.sh
    calling xelatex MASTERPIECE-001-DRAFT... ok!
    calling xelatex MASTERPIECE-001-DRAFT... ok!
    

    If a failure is reported when running XeLaTeX, then there is probably something wrong with the document body.

  8. Open the resulting PDF and check everything went fine.

Handling document revisions

To be explained.

Customizing the document layout

To be explained.

Avaialable macros

To be explained.

Merging and branching

To be explained.

License

techgdoc is copyright (C) 2015 German (jeremy) Theler
techgdoc is licensed under the Apache License, version 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 specific language governing permissions and limitations under the License.