Switch to markdown or rST

[chiphogg]

Could be pandoc-flavored markdown, with prettier for formatting.

[chiphogg]

To test feasibility of writing in markdown, I tried a round-trip conversion using pandoc 2.9.2, from an output .latex file to .md, and back again to .latex.

Before:

\begin{cbunit} 

\chapter{AC METERING CIRCUITS} 
\minitoc 
\bigskip 

\section{ AC voltmeters and ammeters}
\index{Voltmeter}
\index{Ammeter}
\index{PMMC}
\index{Permanent magnet moving coil}
\index{Meter movement}

AC electromechanical meter movements come in two basic arrangements: those based on DC movement designs, and those engineered specifically for AC use.  Permanent-magnet moving coil (PMMC) meter movements will not work correctly if directly connected to alternating current, because the direction of needle movement will change with each half-cycle of the AC. (Figure~\ref{02224})  Permanent-magnet meter movements, like permanent-magnet motors, are devices whose motion depends on the polarity of the applied voltage (or, you can think of it in terms of the direction of the current).

\begin{figure}[htbp!] 
\centering 
\includegraphics{output/02224} 
\caption{\sl Passing AC through this D'Arsonval meter movement causes useless flutter of the needle. } 
\label{02224} 
\end{figure}

\index{D'Arsonval meter movement}
\index{Diode}
\index{Rectifier}

Markdown:

AC METERING CIRCUITS
====================

 AC voltmeters and ammeters
--------------------------

AC electromechanical meter movements come in two basic arrangements:
those based on DC movement designs, and those engineered specifically
for AC use. Permanent-magnet moving coil (PMMC) meter movements will not
work correctly if directly connected to alternating current, because the
direction of needle movement will change with each half-cycle of the AC.
(Figure [1.1](#02224){reference-type="ref" reference="02224"})
Permanent-magnet meter movements, like permanent-magnet motors, are
devices whose motion depends on the polarity of the applied voltage (or,
you can think of it in terms of the direction of the current).

![*Passing AC through this D'Arsonval meter movement causes useless
flutter of the needle.* ](output/02224){#02224}

After:

\hypertarget{ac-metering-circuits}{%
\section{AC METERING CIRCUITS}\label{ac-metering-circuits}}

\hypertarget{ac-voltmeters-and-ammeters}{%
\subsection{AC voltmeters and
ammeters}\label{ac-voltmeters-and-ammeters}}

AC electromechanical meter movements come in two basic arrangements:
those based on DC movement designs, and those engineered specifically
for AC use. Permanent-magnet moving coil (PMMC) meter movements will not
work correctly if directly connected to alternating current, because the
direction of needle movement will change with each half-cycle of the AC.
(Figure~\protect\hyperlink{02224}{1.1}) Permanent-magnet meter
movements, like permanent-magnet motors, are devices whose motion
depends on the polarity of the applied voltage (or, you can think of it
in terms of the direction of the current).

\includegraphics{output/02224}\{\#02224\}

So: the formatting is a bit nicer in the "after", but there are a lot of deficiencies.

• Chapter/section got converted to section/subsection.
• Image captions are lost (though, interestingly, still present in the intermediate markdown!).
• All of the \index labels are dropped.
• \minitoc is dropped.
• hypertarget and hyperlink got added, for some reason.

Based on all of this, it looks like markdown won't be a feasible format for writing, since we need to be able to convert all the existing content to our intermediate format automatically using pandoc or something like it.

[chiphogg]

I tried with .rst as well, and the results were similarly discouraging. However, all hope may not be lost for pandoc flavored markdown. It may be possible to do a little custom processing at the end, or find some similar means of converting to a "good" markdown format, if and when we prove that there's a format good enough to give good latex output.

• Using --top-level-division=chapter can fix the first issue (chapter vs. section).
• Image captions can be restored by removing the {#02224} at the end.
• The need for manual figure numbers (not mentioned above, but noticed later) could be fixed with the "pandoc-fignos" package, which I'll need to research.
• For getting indices to work, this ref seems promising. Note that the HTML indices are currently effectively unused (they do create named anchors, but nothing ever links to them), so we could simply drop support.

[chiphogg]

I'll need to figure out how to handle the <imagen> (non-floating image) figures. These are equivalent to [h!] instead of [htbp!] in the LaTeX output. What in markdown can give this output?

This answer suggests putting a hard linebreak after, but this changes it from a figure into an inline image. Not what we want. (It removes the caption, among other problems.)

Actually... on closer examination, there are no <imagen> at all, and the only instances of <imagenf> are inside hacky, manual <figure> environments (which seem to exist to do subfigures, and which seem to be rare). So maybe we don't need to worry about this.