1

I am using l3doc and DocStrip more and more these days.

Also, I am using more and more LaTeX3 and love the ability, to give the variables and functions readable and meaningfull names. Added with scope and type info, the names tend to be much longer than before.

Actually, I am writing a .dtx file, which contains in fact three (or more) packages. I am using the @@ to give variables and functions a module related name also, which make the names even longer.

When processing the file through LaTeX to generate the documentation, in all code examples, the @@ will be replaced with the last module name mentioned, which is in this case tuc_m_k_calc.

%    \begin{macrocode}
%<*label>
%@@=tuc_m_k_label>
%</label>
%<*concept>
%<@@=tuc_m_k_concept>
%</concept>
%<*calc>
%<@@=tuc_m_k_calc>
%</calc>
%    \end{macrocode}

Therefore, the implementation will show something like this:

\bool_new:N \l_@@_opt_draft_bool

but will be typeset as

\bool_new:N \l_tuc_m_k_calc_opt_draft_bool

This string will be printed into the margin note and the index as well, ignoring the fact, that its sibblings \l_tuc_m_k_concept_opt_draft_bool and \l_tuc_m_k_label_opt_draft_bool are meant and described as well.

I was wondering, if instead printing \l_@@_opt_draft_bool into the documentation wouldn't be a better solution. Obviously, it is space efficient and economic. It is fair, as all three variants are easily met with this description as well. I think, it is even easier to read and understand, as the fully expanded name. (In fact, when fixing bugs, I often wish, LaTeX would reverse the name to the original code, making it more easier for me, to spot the place in the .dtx files.)

This result could easily be achieved, by using this instead of the above mentioned code:

% \iffalse
%    \begin{macrocode}
%<*label>
%@@=tuc_m_k_label>
%</label>
%<*concept>
%<@@=tuc_m_k_concept>
%</concept>
%<*calc>
%<@@=tuc_m_k_calc>
%</calc>
%    \end{macrocode}
% \fi

This would make the documentation more readable (in my eyes).

Do you think, this is a good idea? Are there any sideeffects, I haven't thought of? If you recommend this style, what would be the best way to implement it?

Jan
  • 5,293
  • docstrip does not print anything. docstrip is the tool to unpack dtx files. What will be printed in the documentation depends on the classes and packages used for documentation, e.g., package doc. So please show a minimal working example, that also shows the used documentation class/packages. – cabohah Feb 15 '24 at 12:53
  • @cabohah l3doc is meant here – Joseph Wright Feb 15 '24 at 12:59
  • 1
    https://github.com/latex3/latex3/issues/416 – Joseph Wright Feb 15 '24 at 12:59
  • I am wondering about your setup here: how can you have three sets of variables for submodules that all get setup identically like this? (Also, I'm unclear on your module naming: if your prefix is tuc and submodule is e.g. label, what is m_k about?) – Joseph Wright Feb 15 '24 at 13:01
  • 3
    I must say I would avoid more than on <@@=XXX> in a dtx. That can get very confusing if you move code around. I sometimes forgot to adapt the @@ when I copied from one dtx to another and the errors you get are quite bewildering. – Ulrike Fischer Feb 15 '24 at 13:12
  • @JosephWright IMHO you guess l3doc is meant. The question does nowhere refer to l3doc, neither in the title nor the tags, nor the text of the question. And an example that would help to make this clear is also missing. – cabohah Feb 15 '24 at 13:17
  • @Jan You need to edit your question to make it more clear and without the m_k part, which is not recommended and confusing. The .sty or cls should be left as is, as well as the .pdf documentation file. The .dtx file as you say looks different and difficult to search. Maybe either with the editor or a Lua script can be transformed and get rid of the @@ altogether? there is no particular reason to have them. It is just convenience. I agree with you compactness should be sought. See https://tex.stackexchange.com/questions/698540/how-can-i-improve-the-coloring-of-macrocode-envronments – yannisl Feb 15 '24 at 14:17
  • @UlrikeFischer I prepare a concept, where some items are listed in a LaTeX file. The first package will sort the items by priority and calculate a price. If the concept is accepted, the next package will be used in the same file, to plan with all needed details for each item. If this is also accepted by the client, the items are ordered and the file is typeset a third time with the last package, this time generating order lists and sticky labels, ... The user space macros are identical, same name, same arguments, ... but behind the scenes, really different things are going on. – Jan Feb 15 '24 at 17:15
  • @JosephWright regarding the module names: I maintain a list of packages: all from my employer, which is tuc for short. I tried to organize the packages hierarchically, but this are just misc and related to the key system: so tuc -- misc -- key? To complicated? – Jan Feb 15 '24 at 17:23
  • @JosephWright regarding https://github.com/latex3/latex3/issues/416 this seems to be exact my concern. – Jan Feb 15 '24 at 17:25
  • @yannisl A MWE would consist of a .ins and a .dtx file. Running TeX on the ins file would generate three packages from the one dtx file by simply generating with three different guards active. The guards can be seen in my code example. Running LaTeX on the .dtx file would typeset a pdf file which similar content, as in the three package files. I say similar but not exact, as it actually shows only one module name, while the .ins file uses three different module names. The .sty and .cls used on that packages are irrelevant, as is in my eyes an MWE. The main goal is: is this a good idea? – Jan Feb 15 '24 at 17:47
  • If you doing this for a client as you mentioned then possibly. But then you need to flesh it out and get real feedback from them. But IMHO not a very good idea, the way I understood the problem. Keep it simple is always better. – yannisl Feb 15 '24 at 18:45

0 Answers0