15

I am updating documentation for a simulation model. Each parameter and equation is represented in different ways when found in the source code, primary references, and existing documentation.

(these can be found in the src/ and documentation/ directories of the github repo)

Even within the LaTeX documentation, I have to cross reference a table of parameters when deciphering the equations. But I also have matching these parameters and equations with those found in the source code.

It is a big headache and I imagine that there must be an easier way to cross-reference C source code with LaTeX documentation.

I would like to know if there are already solutions / packages / programs that would help in this task, e.g. by making it easier to

  1. reference equations from inline C documentation.
  2. create new commands in latex named after the parameter names in the C source, e.g. \newcommand{wsun}{\omega_\text{sun}}. This way, at least the parameter names would be consistent (and search friendly) across languages.
  3. parse C code as LaTeX equations, e.g. from a = b*pow(c,2) to a=bc^2 (Mathematica-like, but probably impractical)

Before getting into any of these, I would appreciate guidance. I know of Doxygen but it is not clear that it would provide a full solution.

2
  • 1
    Have you considered using CWEB? Sep 15 '13 at 14:25
  • @SeanAllred I have heard of CWEB, and it is certainly an option. I am familiar with Sweave and org-mode (which I believe are similar (?)). However, for source code, this solution appears less consistent with a standard C-development workflow (and more difficult to debug, etc). Sep 17 '13 at 16:08
9
+50

It's a bit hard to answer as the question has no context as to the desired workflow, do you want to generate the documentation from the source, or the source from the documentation (the normal sense of "literate-programming)) or maintain them separately but make it easier to keep them in sync.

Whichever you choose, there are some things you could do to make things easier. I had a hard time working out from your repository which bit of code was supposed to relate to which section in the doc. labelling the doc with some file names might help.

Main difficulty though was matching the identifiers used in the code with expressions in the documentation source. For that I would change the markup.

instead of using \Phi_N and T_\text{air} use \id{PhiN} and \id{Tair} or some other command than \id, but using the same identifier names as in the source.

You can then use

\def\id#1{%
  \expandafter\ifx\csname id-#1\endcsname\relax
    \mathrm{#1}%
  \else
    \csname id-#1\endcsname
  \fi}

together with

\@namedef{id-Phi}{\Phi}
\@namedef{id-Tair}{T_{\mathrm{air}}

So that it typesets known identifiers the way specified and just uses \mathrm for anything else.

that way it is easy to use a consistent typeset form for all identifiers and easy to switch between code and documentation view of an expression.

Of course you could do similar for functions,if you define

\def\pow(#1,#2){#1^{#2}}

You could write your example as

a = b*\pow(c,2)

again bringing the source and documentation closer.

Once you have it all in sync this way it is not a large step to generate the source expressions from the documentation. Either using TeX itself to write out the code or using perl or similar to just pre-process the files, extracting suitably labelled expressions and inserting them into the C sources at places marked (eg by some stylised comment syntax). If you go this far you have basically implemented your own literate programming system so it might be simpler to have just used one of the *WEB variants, but it has the benefit of being achievable in incremental steps rather than requiring a complete rewrite of the source to a new markup system as an initial stage.

3
  • I kept the "desired workflow" vague because my primary goal is to make documentation easier, less redundant, more accurate. My intuition is that Doxygen source->documentation is preferable to CWEB style documentation-> source because it is easier to debug and more accessible to new developers. Continuing to maintain separate source and documentation is also an option; perhaps one solution would be to maintain a database (even a simple csv table) of the definitions and functions that could be loaded by both documentation and source. Sep 17 '13 at 16:04
  • regarding your suggestion about \def\pow{}{}... by any chance does such a c2latex converter already exist? Sep 17 '13 at 16:05
  • 1
    answer: yes! I'll have to take a look: ctan.org/pkg/c2latex and mirrors.ibiblio.org/CTAN/support/c2latex/c2latex.c Sep 17 '13 at 16:16

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.