General ⇒ Packaging custom module or layout

[aparfeno]

Hello,
At my company we use lyx to create giant user manuals in PDF formats. We've organized our work similar to software development lifecycle:

Technical authors (on personal workstations computers) -> SVN -> Jenkins(build server) -> PDF -> Automatic distribution of PDF documents.
So:
1. All document sources (*.lyx and images) live in SVN
2. Since the documents are large, we split them up into multiple parent-child lyx files.

Question:
How can I implement custom templates, global document settings and keep them in SVN (ideally in one place)?
I has hoping to use \input or \include feature, but it seems that it is not possible to include a module by file name (it must be added to local environment)?

Thanks,
Alex

[Stefan Kottwitz]

Hi Alex,

welcome to the forum!

When I produce documentation in PDF format, I use LaTeX. Like you, I try to keep it simple for my colleagues and me. Instead of LyX, I use LaTeX but I separate content and style. I go so far, that I write pure content without commands. (only macros when needed)

For this, I use Markdown. Any simple editor can be used by anybody. Documents look like this:

Code: Select all

\input{header}
\begin{markdown}

Overview
========

This document is a summary of the Cisco solution at \location of \customer:

- General architecture and functionality
- Setup at \location
- \location specific configuration
- Administration by \customer, \location IT and GIS

Wired LAN
---------

The \location network contains Cisco Catalyst 3650 switches in the IDF rooms and Cisco  Nexus switches in the MDF rooms that are the data centers (DCs). The DCs also contain Catalyst switches, routers, and WiFi controllers.

The header contains the style file and macros. Using the simple Markdown syntax, text is clean and readable and maintainable. Still I have the full power of LaTeX. Running LaTeX, I get such output for the document above:

document.png (58.46 KiB) Viewed 2153 times

Documentation doesn't need sophisticated code. It's often just headings, bullet points, lists, code, images (the latter loaded via simple macro). In general, using simple macros allows to re-use the same technical documentation for the same product for several different projects for the same customer or even different customers.

Stefan