Text Formatting ⇒ Macro for 100's/1000's of code blocks

[JBC]

Hello LaTeX,

My objective with LaTeX seems fairly complex...but that's probably just me.
I hope to share my overall objective, software and system, progress so far, and the piece that I'm trying to solve at this stage of the game to see if I'm walking down the right path. Thank you in advance.

Objective
The project is writing documentation in Markdown for a text editing program. The object is to write the content once, and then either convert it from Markdown to Tex and then finish the output to HTML, PDF, ePub & Mobi...
...OR...
...run the markdown through a script first to manually prepare it for becoming a TEX file that can then output the preferred formats.
Question 1: Is this even feasible, and even if it is, should I have high expectations for the output quality of each format?

Software
Running Windows 7, MikTex, flirted with Overleaf online, TeXworks is installed but 99% of my initial attempts have used a text editor to edit the file, then compiled at prompt with pdflatex file.tex. TikZ is also on my system but don't see the need for my doc. My system seems capable enough.

Progress
So I've been able to compile a VERY basic PDF to try and learn what the heck I'm doing. Adding \packages to the preamble, have them install automatically when needed etc.

Problem piece.
There are going to be approximately 1,500 references to software commands (one to 20 characters long) in this document. I've created a conceptual visual structure for these commands that I was hoping to implement with a \newcommand macro. An image is attached. The styling for this image is due to the settings in the next paragraph.

This provides the visual effect for each insertion seen in the attached file, colors are just for concept.
\colorbox{black}{\lstinline[basicstyle=\ttfamily\color{yellow}\large]|yy|}. I just haven't been able to figure out how to incorporate it into a \newcommand.

I've tried to grasp the \newcommand macro framework because it seems it would make the most sense based on the content volume but wow...I feel really stupid. Here's what I was thinking:

\newcommand{command}{description}{category?} etc.
\code{aa} {desc}
\code{bb} {desc}
\code{cc} {desc}
\code{dd} {desc}
\code{ee} all throughout the document. It seems the \newcommand could handle the formatting and everything would be formatted similar to the \colorbox setting above but can you imagine having that size string 1,000 times in a document? So besides the visual formatting, it looks like I'll need two parameters, {command} and {description}.

Future thoughts
Then there's the thought of multi column layout, index, table of contents, categorizing the same piece of content potentially multiple times for it to appear in every section of the book that makes sense etc. etc. Forgive me for rambling...really I'm just hoping to see if I'm in the right country before I get this narrowed down to a street address.

Is this feasible?
Am I on the right software path?
Is it a realistic expectation to take a single TEX file and produce four different quality file formats of PDF, ePub, Mobi & HTML?

Does the \newcommand macro approach make sense?
Can the \colorbox sequence above be written once and used hundreds/thousands of times for design purposes?

I understand this first post is far too long, but there's no sense in spreading it over 5 posts only to find out this project should use a different approach.

Oh please ignore the cascading text in attached PDF...that's me testing stuff.

Thank you VERY much Stefan!!

Brett

[Stefan Kottwitz]

Hi Brett,

regarding Markdown: I use Markdown for writing documentation. The advantage is, that my colleagues don't have to deal with LaTeX, but LaTeX is used in the backend, as template, and for macros or tweaking it. With the markdown package I can write Markdown right within LaTeX, for documentation such as manuals but also for presentations.

Regarding the macros: yes, always put formatting in macros, so its easy to change globally, and don't repeat things. Example:

Code: Select all

\documentclass{article}
\usepackage{xcolor}
\usepackage{listings}
\newcommand{\lbox}[2]{%
  \colorbox{black}{\lstinline[basicstyle=\ttfamily\color{#1}\large]|#2|}
}
\begin{document}
\lbox{yellow}{yy}

\lbox{white}{zz}
\end{document}

Btw. please let's always discuss one topic in such a thread. Better write several posts, one for each topic. It's hard to mix Markdown and color boxes in an ongoing thread, also for future readers who come in via google.

Stefan

[Stefan Kottwitz]

Here is a snipped of a LaTeX from my documentation:

Code: Select all

\input{header}

\begin{markdown}

General architecture
====================

Wired LAN
---------

The equipment consists of these Cisco switches:

- Nexus 7k core switches in the MDF rooms that are the data centers (DCs)
- Nexus 5k distribution switches in the MDF (DCs)
- Catalyst 3850 distribution switches in the DC
- Catalyst 3650 acces switches in the IDF rooms

\end{markdown}
\end{document}

Easy to read, easy to maintain. This will automatically translated to \section, \subsection, and an itemize list. In documentation text, not much more is needed, let's say enumerate (supported by Markdown) and images (create a short macro for including with options).

The header.tex looks like:

Code: Select all

\documentclass[12pt,DIV12,numbers=enddot,halfparskip]{scrartcl}
\usepackage{graphicx} % Required for including images
\graphicspath{{images/}} % Specifies the directory where pictures are stored
\usepackage[T1]{fontenc}% font encoding
\usepackage[utf8]{inputenc}% file encoding
\usepackage{microtype}% better fine typography
\usepackage{xspace}% for text macros
\usepackage{tabularx}% tables of line width
\usepackage[colorlinks]{hyperref}
\usepackage[svgnames]{xcolor}
\usepackage[tightLists=false,hybrid=true]{markdown}
\usepackage{booktabs}
\renewcommand*{\familydefault}{\sfdefault}% sans serif documentation
\usepackage{lmodern}% font
\usepackage{scrlayer-scrpage}
\clearscrheadfoot
\ohead{\raisebox{-15mm}{\includegraphics[height=1.2cm]{logo}}}
\cfoot{Manual for ...}
\usepackage{lastpage}
\ofoot{Page \thepage\ of \pageref*{LastPage}}
\addtokomafont{pagefoot}{\upshape}
\pagestyle{scrheadings}
\usepackage{pdfpages}
\newcommand*{\mytitle}{
\thispagestyle{scrheadings}
\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here
\raggedleft
\vspace*{6cm}
%\textsc{\Large Company}\\[1cm]
%\textsc{\large for}\\[0.5cm]
%\textsc{\LARGE Customer}\\[1cm]

%\HRule\\[0.4cm]
{ \huge \bfseries Project XX}\\[0.4cm] % Title of your document
\large Company\\
Version yy
%\HRule\\[1.5cm]
\vspace*{6cm}

\large
Stefan Kottwitz % Your name

{\large Oct 10, 2017}\\[3cm] % may be changed to \today

\vfill
}
\begin{document}
\tableofcontents
\clearpage
\listoffigures
\clearpage

You see, it's just LaTeX. The point here is:

\usepackage[tightLists=false,hybrid=true]{markdown}

I still use macros, glossaries for lists of abbreviations, and indexing. So there are some \commands still within the markdown code, but not the{hell of {\LaTeX{} braces}}.

Stefan

[JBC]

Hello Stefan,

Thank you for taking SO MUCH time with your answer. Focused single topic posts moving forward...will do. With all the content in your answer, it will probably take me a month to try and understand...here goes.

Thank you again!

Brett