[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Request for Features in DocTeX mode
From: |
Jan Braun |
Subject: |
Re: Request for Features in DocTeX mode |
Date: |
Tue, 28 Mar 2023 18:01:32 +0200 |
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 … ===
- Request for Features in DocTeX mode, Jan Braun, 2023/03/27
- Re: Request for Features in DocTeX mode, David Kastrup, 2023/03/27
- Re: Request for Features in DocTeX mode, Arash Esbati, 2023/03/28
- Re: Request for Features in DocTeX mode,
Jan Braun <=
- Re: Request for Features in DocTeX mode, Arash Esbati, 2023/03/29
- Re: Request for Features in DocTeX mode, Dirk Ullrich, 2023/03/29
- Re: Request for Features in DocTeX mode, Arash Esbati, 2023/03/29
- Re: Request for Features in DocTeX mode, Ikumi Keita, 2023/03/30
- Re: Request for Features in DocTeX mode, Arash Esbati, 2023/03/31