LaTeX forum ⇒ Text FormattingMacro for 100's/1000's of code blocks

Information and discussion about LaTeX's general text formatting features (e.g. bold, italic, enumerations, ...)
Posts: 5
Joined: Sat Nov 18, 2017 1:37 am

Macro for 100's/1000's of code blocks

Postby JBC » Mon Nov 20, 2017 4:54 pm

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.

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... 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?

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.

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!!

(55.59 KiB) Downloaded 20 times


User avatar
Stefan Kottwitz
Site Admin
Posts: 8945
Joined: Mon Mar 10, 2008 9:44 pm

Postby Stefan Kottwitz » Tue Nov 21, 2017 3:27 pm

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:

  1. \documentclass{article}
  2. \usepackage{xcolor}
  3. \usepackage{listings}
  4. \newcommand{\lbox}[2]{%
  5. \colorbox{black}{\lstinline[basicstyle=\ttfamily\color{#1}\large]|#2|}
  6. }
  7. \begin{document}
  8. \lbox{yellow}{yy}
  10. \lbox{white}{zz}
  11. \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.

Site admin

User avatar
Stefan Kottwitz
Site Admin
Posts: 8945
Joined: Mon Mar 10, 2008 9:44 pm

Postby Stefan Kottwitz » Tue Nov 21, 2017 3:41 pm

Here is a snipped of a LaTeX from my documentation:

  1. \input{header}
  3. \begin{markdown}
  5. General architecture
  6. ====================
  8. Wired LAN
  9. ---------
  11. The equipment consists of these Cisco switches:
  13. - Nexus 7k core switches in the MDF rooms that are the data centers (DCs)
  14. - Nexus 5k distribution switches in the MDF (DCs)
  15. - Catalyst 3850 distribution switches in the DC
  16. - Catalyst 3650 acces switches in the IDF rooms
  18. \end{markdown}
  19. \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:

  1. \documentclass[12pt,DIV12,numbers=enddot,halfparskip]{scrartcl}
  2. \usepackage{graphicx} % Required for including images
  3. \graphicspath{{images/}} % Specifies the directory where pictures are stored
  4. \usepackage[T1]{fontenc}% font encoding
  5. \usepackage[utf8]{inputenc}% file encoding
  6. \usepackage{microtype}% better fine typography
  7. \usepackage{xspace}% for text macros
  8. \usepackage{tabularx}% tables of line width
  9. \usepackage[colorlinks]{hyperref}
  10. \usepackage[svgnames]{xcolor}
  11. \usepackage[tightLists=false,hybrid=true]{markdown}
  12. \usepackage{booktabs}
  13. \renewcommand*{\familydefault}{\sfdefault}% sans serif documentation
  14. \usepackage{lmodern}% font
  15. \usepackage{scrlayer-scrpage}
  16. \clearscrheadfoot
  17. \ohead{\raisebox{-15mm}{\includegraphics[height=1.2cm]{logo}}}
  18. \cfoot{Manual for ...}
  19. \usepackage{lastpage}
  20. \ofoot{Page \thepage\ of \pageref*{LastPage}}
  21. \addtokomafont{pagefoot}{\upshape}
  22. \pagestyle{scrheadings}
  23. \usepackage{pdfpages}
  24. \newcommand*{\mytitle}{
  25. \thispagestyle{scrheadings}
  26. \newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here
  27. \raggedleft
  28. \vspace*{6cm}
  29. %\textsc{\Large Company}\\[1cm]
  30. %\textsc{\large for}\\[0.5cm]
  31. %\textsc{\LARGE Customer}\\[1cm]
  33. %\HRule\\[0.4cm]
  34. { \huge \bfseries Project XX}\\[0.4cm] % Title of your document
  35. \large Company\\
  36. Version yy
  37. %\HRule\\[1.5cm]
  38. \vspace*{6cm}
  40. \large
  41. Stefan Kottwitz % Your name
  43. {\large Oct 10, 2017}\\[3cm] % may be changed to \today
  45. \vfill
  46. }
  47. \begin{document}
  48. \tableofcontents
  49. \clearpage
  50. \listoffigures
  51. \clearpage

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


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}}. ;-)

Site admin

Posts: 5
Joined: Sat Nov 18, 2017 1:37 am

Postby JBC » Tue Nov 21, 2017 7:15 pm

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 goes.

Thank you again!


Return to “Text Formatting”

Who is online

Users browsing this forum: No registered users and 5 guests