1

I'm looking for some standard ou good practices to document LaTeX source code.

I know the package doc to manage sty files, but I'm looking for how to put comments in the document itself (tex files).

I saw plenty of documents using meta-comments starting with %! and it seems to be very tool dependent, as TeXStudio comments differ from those in IntelliJ, for example.

This is from TeXStudio:

% ! TeX program = pdfduallist.sh % | txs:///view

And this is from IntelliJ Idea:

%! suppress = MightBreakTexify
%! suppress = FileNotFound
%! Package = LINGUAGEM
%! Author = Jander
%! Date = 23/04/2022

Is there a common ground on such kind of comments? I couldn't find any reference about it.

Other options are also welcome.

(I'm currently using IntelliJ IDEA).

Jander
  • 1,128
  • those comments are not using comments for documentation, but rather as pragmas to control the processing flow by the editor. If you just want to document the document (with author or change log or whatever) most pople just use unstructured % comments, I think. – David Carlisle Apr 27 '22 at 18:41
  • Alas, undocumented code is the standard. See also the comment package. – John Kormylo Apr 27 '22 at 19:08
  • I understand these comments are meant to the editor. I wanted to know if could be a standard used by several distinct editors, so I could use as a general documenting standard for me. I am a professor and also a programmer (C and Python), documenting is in my core. :-) Thanks a lot for the your comments! – Jander Apr 28 '22 at 12:26
  • https://tex.stackexchange.com/questions/78101/when-and-why-should-i-use-tex-ts-program-and-tex-encoding/78352 covers 'magic' comments for the editors, but if you want structured documentation of sources, that is what doc is for. I guess we might need some example of what you are after. – Joseph Wright Apr 28 '22 at 18:36

1 Answers1

2

I'm not really sure about your question, especially after reading your comment.

The doc system is the standard way of documenting LaTeX (package/class) files, mixing code and explanations, although it seems to have gone out of fashion with many authors.

Many years ago I created the docmfp system as an extension of doc with the main aim of providing doc-like Metafont/Metapost commented code.

I also used it for creating and documenting C and express (an ISO information modelling language) codes. docmfp was in general created with the idea of being able, in a single fashion, to document any programming code. The output was ASCII text files.

Take a look at docmfp and see if it might go some way towards what you are after. Any editor should be able to handle ASCII text files.

Peter Wilson
  • 28,066