[I] Snippet macro: decide whether de-indentation should be opt-in [maven-doxia]

["slachiewicz (via GitHub)" <gi...@apache.org>]

slachiewicz opened a new issue, #1084:
URL: https://github.com/apache/maven-doxia/issues/1084

   Splitting the open design question out of #161 so that PR is not the only place it lives.
   
   `SnippetReader` strips the common leading indentation from an included snippet, so a deeply nested example does not render with a horizontal scrollbar. #161 (open since March 2023) points out two defects in how that is done: the `minIndent` calculation only counts spaces, so tab-indented sources keep their indentation, and it computes 0 whenever the snippet starts at column 0.
   
   The patch itself is small. What stalled it was whether the stripping is right at all. From the discussion there:
   
   > But what if
   > ```
   >               {
   >                       // your code
   >               }
   > ```
   > is correct indentation?
   
   and
   
   > I would prefer to leave formatting as-is, but I am open to a snippet option
   
   The contributor accepted that and the thread went quiet, so the bug is still present: snippets indented with tabs render differently from snippets indented with spaces, which is hard to justify either way.
   
   Three ways out:
   
   1. Fix the tab handling and keep stripping unconditional — consistent, but keeps removing indentation from people who wanted it.
   2. Add a snippet parameter, defaulting to current behaviour, so authors can opt out. This is the option floated in the thread.
   3. Stop stripping by default and make it opt-in — cleanest semantics, but changes rendering for existing sites, so 2.x is the wrong place for it.
   
   Option 2 looks like the one that fixes the inconsistency without changing anyone`'`s output. Worth settling the direction here before asking anyone to rework #161.
   
   *This issue was created with AI assistance.*


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [I] Snippet macro: decide whether de-indentation should be opt-in [maven-doxia]

["slachiewicz (via GitHub)" <gi...@apache.org>]

slachiewicz closed issue #1084: Snippet macro: decide whether de-indentation should be opt-in
URL: https://github.com/apache/maven-doxia/issues/1084


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org