Re: Request for Features in DocTeX mode

[Jan Braun]

Hi Arash, :-)

> Am 28.03.2023 um 10:18 schrieb Arash Esbati <arash@gnu.org>:
> 
> Jan Braun <Jan.Braun@klein-gallien.org> writes:
> 
>> When in LaTeX mode, you can use AUCTeX or reftex to insert a 
>> \ref command and Emacs will ask you, about the labels to use.  
>> It will also auto-complete known labels.  When doing the 
>> same in a DocTeX buffer, Emacs fails to offer any label.  There
>> is also no LaTeX-add-labels in the corresponding auto files.
> 
> This sounds like this question:
> 
>  https://emacs.stackexchange.com/q/68377/12242

Indeed.

Thank you, I had forgotten about the % sign.  So with refTeX you 
can get along/work around.   

But for pure AUCTeX, this seems not be possible?

>> When in DocTX mode inserting sectioning commands, AUCTeX will 
>> always suggest the topmost command, which is \section, 
>> regardless of the document structure. For example: in an 
>> regular LaTeX buffer, when the last section command was 
>> — lets say — a \subsection, AUCTeX would normally offer to 
>> insert a \subsection again.  In DocTeX mode, it will always 
>> suggest a \section.
> 
> I think this can be fixed by changing `LaTeX-outline-regexp' and
> `LaTeX-outline-level':

[…]

your fix seems to work for me.  Thank you very much!

> Not sure about any side effects, though.

I will report.  Promised!

>> One very difficult thing is indentation.  If you make use of the 
>> documentation possibilities of DocTeX, you will surely split 
>> your code on multiple occasions, to insert some interesting 
>> documentary thoughts about what, why, ...
>> 
>> Both code and documentation follow different rules of indentation 
>> or at least a different base of indentation to compute the level 
>> of indentation for the next line.  DocTeX struggles, to keep a 
>> clean indentation for both parts.
> 
> This statement is generic, can you provide an example and a recipe how
> to reproduce that example?

Yes, of course.

Here you are, fresh from my actual work in progress.

This is a snippet from the DTX file with an indentation as it 
should be.

% \begin{macro}{\@@_set_option_defaults:}
%   \TestFiles{options}
%   \UnitTested
%   Diese Funktion sorgt dafür, dass zu Beginn einer Aktion, alle 
%   Optionen auf die normalen Standardwerte zurück gesetzt werden.
%    \begin{macrocode}
\cs_new:Npn \@@_set_option_defaults:
  {
    \tl_gset:Nn \g_@@_handle_code_tl {U}
%    \end{macrocode}
%   Wenn es sich um einen DIN- oder One"=Din"=Beschlag handelt, 
%   dann ist der Default für den Abstand nicht \enquote{00}, 
%   sondern \enquote{SH}. 
%    \begin{macrocode}
    \str_case_e:nn
       \l_@@_bracket_type_tl 
      { 
        { xs } { \tl_gset:Nn \g_@@_distance_code_tl {00} }
        { one }  { \tl_gset:Nn \g_@@_distance_code_tl {00} }
        { xsdin } { \tl_gset:Nn \g_@@_distance_code_tl {SH} }
        { onedin } { \tl_gset:Nn \g_@@_distance_code_tl {SH} }
      }
%    \end{macrocode}
%   Alle anderen Parameter werden wie üblich gesetzt.
%    \begin{macrocode}
    \tl_gset:Nn \g_@@_material_code_tl {IM}
    \tl_gset:Nn \g_@@_readercolor_code_tl {B}
    \tl_gset:Nn \g_@@_thickness_code_tl {-}
    \tl_gset:Nn \g_@@_shanksize_code_tl {8}
    \tl_gset:Nn \g_@@_sealing_code_tl {}
    \tl_gset:Nn \g_@@_reinforcement_code_tl {}
  }
%    \end{macrocode}
% \end{macro}

Go to one of the document lines (those beginning with the %), hit 
TAB and the indentation of that line will be changed.  For example, 
lets take the \TestFiles{…}line, which atually looks like this:

%   \TestFiles{options}

After indenting it will look like this:

% \TestFiles{options}

Go to one of the code implementation lines (those not starting 
with %) and reindent them.  Lets take this line:

    \str_case_e:nn

and it will become

\str_case_e:nn

TeX and LaTeX won’t mind, but the resulting style file will have
strang indentations.

>> [Breaking up implementation by documentation …]
>> 
>>  \newpage
>> %    \end{macrocode}
>> % @
>> %    \begin{macrocode}
> 
> I don't understand this requirement.  Why don't you use 'C-c C-e' to
> insert the macrocode environment?  You can then do whatever you want
> inside or around the environment.

Again an example from my daily routine.

The following lines represent implementation code, which is, btw, 
indented as it should: 

%    \begin{macrocode}
\cs_new:Npn \_@@_set_option_defaults:
  {
    \tl_gset:Nn \g_@@_handle_code_tl {U}
    \str_case_e:nn
       \l_@@_bracket_type_tl
      {
        { xs } { \tl_gset:Nn \g_@@_distance_code_tl {00} }
        { one }  { \tl_gset:Nn \g_@@_distance_code_tl {00} }
        { xsdin } { \tl_gset:Nn \g_@@_distance_code_tl {SH} }
        { onedin } { \tl_gset:Nn \g_@@_distance_code_tl {SH} }
      }
    \tl_gset:Nn \g_@@_material_code_tl {IM}
    \tl_gset:Nn \g_@@_readercolor_code_tl {B}
    \tl_gset:Nn \g_@@_thickness_code_tl {-}
    \tl_gset:Nn \g_@@_shanksize_code_tl {8}
    \tl_gset:Nn \g_@@_sealing_code_tl {}
    \tl_gset:Nn \g_@@_reinforcement_code_tl {}
  }
%    \end{macrocode}

After having tested the code to work and to deliver the desired 
results, I decide to insert a piece of documentation between 
\tl_gset:Nn and \str_case_e:nn (or wherever you prefer).  I type 
C-c C-e macrocode RET and will get this result:

%    \begin{macrocode}
\cs_new:Npn \_@@_set_option_defaults:
  {
    \tl_gset:Nn \g_@@_handle_code_tl {U}
%    \begin{macrocode}
@
%    \end{macrocode}
\str_case_e:nn
       \l_@@_bracket_type_tl
      {
        …
      }
  }
%    \end{macrocode}

This will result in an error when compiling the documentation 
document or when extracting the style file.  

(I inserted the @-sign to mark point.)

C-c C-e macrocode inserted the following snippet

%    \begin{macrocode}
@
%    \end{macrocode}

but needed was this:

%    \end{macrocode}
% @
%    \begin{macrocode}

Please note: the \end{macrocode} has to come first and has to end 
with \start{macrocode}.  Like an inverted environment, so to speak.

Transposing the lines (C-x C-t) will not do the trick.  You’d have 
to fiddle it three times, combined with some cursor movement: 

  C-x C-t C-x C-t C-p C-p C-x C-t C-p % TAB

Would do.  I personally think, this is not appealing.

>> [inserting guards …] But before insertig, it’ll 
>> present you a list of know guards in the minibuffer and help you via 
>> auto-completion to find the correct one, you desire.  Wouldn’t that be 
>> a nice thing to have?
> 
> Not sure how nice that is.  I'd say it is doable, but I'm not sure how
> needed this is.

It depends on how often and how many guards you insert into your 
code.  

>> [Visibility of guarded code …]
> 
> I'm not sure how this can done for a construct like:
> 
> %<*!foo&!bar>
> code and/or text
> %</!foo&!bar>

But you got my point. :-)

Bye

   Jan

-- 
Jan Braun (er/ihm)
Jan.Braun@klein-gallien.org


=== ypchsh /usr/local/bin/emacs === go FORTH now … ===