Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise chomp and fold settings in reference documentation #30001

Closed
sbrannen opened this issue Feb 20, 2023 · 0 comments
Closed

Revise chomp and fold settings in reference documentation #30001

sbrannen opened this issue Feb 20, 2023 · 0 comments
Assignees
Labels
type: documentation A documentation task
Milestone

Comments

@sbrannen
Copy link
Member

While analyzing the claim in #29998, I became aware of our current settings for chomp and fold for spring-asciidoctor-backends in the reference documentation.

:chomp: default headers packages
:fold: all

Historically, we have maintained handcrafted code examples (in contrast to included snippets which we have recently introduced for AOT examples), sometimes with explicit package and import statements in order to assist the user in understanding the examples. For example, the CommonPointcuts class explicitly declares its package com.xyz.myapp to make it clear in subsequent examples where shared pointcuts are derived from (e.g., com.xyz.myapp.CommonPointcuts.businessService()).

As far as I understand the feature set of spring-asciidoctor-backends, it is not possible to "un-chomp" (i.e., show) chomped package statements; whereas, it is possible to un-fold folded import statements (even if not readily apparent to the user).

However, for handcrafted examples that intentionally include package and import statements I think we should show those by default, especially since the user has no way to show the package statements that have been chomped.

On the other hand, if the package statement is irrelevant -- for example, when including code snippets from a real source file in the framework-docs project -- it then makes sense to chomp package statements.

I am therefore creating this issue for the team to decide how to deal with chomping and folding defaults across the reference documentation, specifically with regard to handcrafted vs. included code snippets.

@sbrannen sbrannen added this to the 6.0.6 milestone Feb 20, 2023
@sbrannen sbrannen self-assigned this Feb 21, 2023
@sbrannen sbrannen changed the title Reassess chomp and fold settings in reference documentation Revise chomp and fold settings in reference documentation Feb 22, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: documentation A documentation task
Projects
None yet
Development

No branches or pull requests

1 participant