Text wrap long trailing comments

[LogCreative]

There seems to be no option to text wrap long trailing comments. Sometimes, the trailing comment is too long and exceeds the columns limit in textWrapOptions. I wonder if there is a way to text wrap the trailing comments and automatically add % when the next comment line starts.

original .tex code

% This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.

yaml settings

modifyLineBreaks:
  textWrapOptions:
    columns: 80

actual/given output

% This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.

desired or expected output

% This is a very very long trailing comment that needs to be wrapped by
% latexindent to make sure the visual display is in a good shape.

In fact, it is really helpful for formatting .dtx files. Some implementation for indent is found in #248 to avoid indenting doc comments. But I think there is no obvious workaround to text wrap the doc comments in the current version.

As I ran the command

latexindent -w -l latexindent.yaml -m -sl -tt test.dtx

and found that it is storing the trailing comments and then return it back when the text-wrapping is finished.

TRACE: Storing trailing comments
       Trailing comments stored in:
       [
         {
           id => "latexindenttrailingcomment1-END",
           value => " This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape."
         }
       ]

TRACE: condense blank lines routine
       Condensing multiple blank lines into 1 (see condenseMultipleBlankLinesInto)
       blank line replacement token: LTXIN-TK-blank-line
       body now looks like:
       %latexindenttrailingcomment1-END
       Unprotecting blank lines (see preserveBlankLines)
       Finished unprotecting lines (see preserveBlankLines)
       body now looks like:
       %latexindenttrailingcomment1-END
TRACE: Returning trailing comments to body
       replace %latexindenttrailingcomment1-END with % This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.

I saw no switch in TrailingComments.pm to disable the process to treat the trailing comment as normal text so that it could be text wrapped (but no additional % after the line break will turn into an error). I guess it could be implemented by adding an option and adding another cycle to text wrap the trailing comments before it is returned to the body.

[cmhughes]

Thanks for this, it's interesting :)

There seems to be no option to text wrap long trailing comments.

Yes, you're correct, there's not currently an option for this.

Perhaps an option like the following could be helpful to build?

modifyLineBreaks:
  textWrapOptions:
    columns: 80
    wrapComments: 1                    # <---- NEW BIT?????

to consider

What about for scenarios like the following

text that isn't commented % This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.

Would this go to

text that isn't commented % This is a very very long trailing comment that needs to be
% wrapped by latexindent to make sure the visual display is in a good shape.

[LogCreative]

It sounds good to me to add an option to text wrap the comments :)

As for a mixed scenario with the text that isn't commented, I think the output is fine, but there may be variants that someone wants:

• Comments is on the same line with the normal text. It makes sense since it is what "trailing" comment means.
• Someone may want the long comment to be the next line of the normal text, which may look better, like

text that isn't commented
% This is a very very long trailing comment that needs to be wrapped by
% latexindent to make sure the visual display is in a good shape.

• "doc" comment lines (especially in dtx files) start with % with no normal text. I believe they have already written the code like this:

% This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
text that isn't commented

and goes with the normal trailing comment wrapping:

% This is a very very long trailing comment that needs to be wrapped by
% latexindent to make sure the visual display is in a good shape.
text that isn't commented

Hope that nobody wants to rearrange the comment into the former position of the normal text. Since it is not controllable and it is unknown for the program where the normal text starts.

The discussion above is more like the poly-switch concept. I think keeping the comment on the same line is already acceptable to me.

[LogCreative]

And the new option may also introduce some complexities here, refer to the documentation:

setting columns to a value > 0 will text wrap blocks by first removing line breaks, and then wrapping according to the specified value of columns;

Since we may add a new % symbol here, when removing line breaks it may also keep the % in the line causing

text that isn't commented % This is a very very long trailing comment that needs to be % wrapped by latexindent to make sure the visual display is in a good shape.

I think the nearby comment blocks need to be considered and merge them into one comment before storing them. the additional spaces that is introduced from this action will need to be condensed into one space.

Also, there may be some cases that the spaces after % character is more than one:

%    This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.

the preferable output is

%    This is a very very long trailing comment that needs to be wrapped
%    by latexindent to make sure the visual display is in a good shape.

which keeps the same spaces (or tabs) after the symbol.

[cmhughes]

This is implemented as of b8ab9f1

In brief, new options are available:

modifyLineBreaks:
  textWrapOptions:
    comments: 
      wrap: 1
      inheritLeadingSpace: 1

This will be part of the next release (hopefully early 2023); feel free to pull from develop if you'd like it until then.

demonstration 1

Starting with

here is some leading text % This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.

and using

modifyLineBreaks:
  textWrapOptions:
    columns: 40
    comments: 
      wrap: 1   

gives

here is some leading text % This is a
% very very long trailing comment that
% needs to be wrapped by latexindent to
% make sure the visual display is in a
% good shape.
----|----|----|----|----|----|----|----|
   5   10   15   20   25   30   35   40

demonstration 2

Starting with

here is some leading text % This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
another piece of text to be wrapped % Second comment: this is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.

and using

modifyLineBreaks:
  textWrapOptions:
    columns: 40
    comments: 
      wrap: 1   

gives

here is some leading text another piece
of text to be wrapped % This is a very
% very long trailing comment that needs
% to be wrapped by latexindent to make
% sure the visual display is in a good
% shape. Second comment: this is a very
% very long trailing comment that needs
% to be wrapped by latexindent to make
% sure the visual display is in a good
% shape.
----|----|----|----|----|----|----|----|
   5   10   15   20   25   30   35   40

demonstration 3

Stating with

% This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
% Second comment 
% Third is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
% fourth comment 


% This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
% Second comment 
% Third is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
% fourth comment 

and using

modifyLineBreaks:
  textWrapOptions:
    columns: 40
    comments: 
      wrap: 1   

gives

% This is a very very long trailing
% comment that needs to be wrapped by
% latexindent to make sure the visual
% display is in a good shape. Second
% comment Third is a very very long
% trailing comment that needs to be
% wrapped by latexindent to make sure
% the visual display is in a good shape.
% fourth comment 

% This is a very very long trailing
% comment that needs to be wrapped by
% latexindent to make sure the visual
% display is in a good shape. Second
% comment Third is a very very long
% trailing comment that needs to be
% wrapped by latexindent to make sure
% the visual display is in a good shape.
% fourth comment 
----|----|----|----|----|----|----|----|
   5   10   15   20   25   30   35   40

demonstration 4

Starting with

%     This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
%   Second comment 
% Third is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
% fourth comment 


% This is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
% Second comment 
% Third is a very very long trailing comment that needs to be wrapped by latexindent to make sure the visual display is in a good shape.
% fourth comment 

and using

defaultIndent: '    '
modifyLineBreaks:
  textWrapOptions:
    columns: 40
    when: after
    comments: 
      wrap: 1
      inheritLeadingSpace: 1

gives

%     This is a very very long trailing
%     comment that needs to be wrapped
%     by latexindent to make sure the
%     visual display is in a good shape.
%     Second comment Third is a very
%     very long trailing comment that
%     needs to be wrapped by latexindent
%     to make sure the visual display is
%     in a good shape. fourth comment 

% This is a very very long trailing
% comment that needs to be wrapped by
% latexindent to make sure the visual
% display is in a good shape. Second
% comment Third is a very very long
% trailing comment that needs to be
% wrapped by latexindent to make sure
% the visual display is in a good shape.
% fourth comment 
----|----|----|----|----|----|----|----|
   5   10   15   20   25   30   35   40

[cmhughes]

This is part of V3.20 at https://github.com/cmhughes/latexindent.pl/releases/tag/V3.20. I've uploaded it to ctan. Many thanks!

[LogCreative]

Thank you for the excellent work!