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

Use more descriptive reference style #138

Merged
merged 2 commits into from
May 14, 2020

Conversation

hirotnk
Copy link
Collaborator

@hirotnk hirotnk commented May 11, 2020

Reference:
https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/xrefstyle.adoc

To me, it looks better to be able to see chapter/appendices, etc. @happi if you prefer other style I can make a change accordingly.

Before:
ref-before
After:
ref-after

@happi
Copy link
Owner

happi commented May 11, 2020

OK, lets try it.
At some places I feel the reading flows easier with just the name of the chapter instead off the full reference. Best thing would probably be to have explicit short and long references in the text.

@hirotnk
Copy link
Collaborator Author

hirotnk commented May 11, 2020

Thank you for the feedback, then I will look into this a bit more to see if there is a better option.

@hirotnk
Copy link
Collaborator Author

hirotnk commented May 12, 2020

@happi I checked several technical books and noticed the style like Chapter 8 or Section 3.4 are popular. So I'd like to change to that style. I think this is more like a matter of taste, but for now, I propose to pick that style.

@happi
Copy link
Owner

happi commented May 12, 2020

Fine.

After some discussion and looking at several technical books, this seems
to be the popular style, and picking this one for now.
@hirotnk
Copy link
Collaborator Author

hirotnk commented May 12, 2020

Thank you, updated.
ref-short

@hirotnk hirotnk merged commit 952eeb9 into happi:master May 14, 2020
@hirotnk hirotnk deleted the improve-reference-style branch May 14, 2020 04:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants