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

In the split-HTML version of the tutorial, name sections instead of numbering them #2102

Open
nyh opened this issue Feb 13, 2024 · 0 comments
Labels
documentation Documentation - the tutorial, doxygen comments, etc.

Comments

@nyh
Copy link
Contributor

nyh commented Feb 13, 2024

We have in doc/ the scripts md2html and htmlsplit.py that convert tutorial.md into HTML pages that can be seen in https://docs.seastar.io/master/tutorial.html (single HTML page for the entire tutorial) and https://docs.seastar.io/master/split/ (multi-page version, one page per section).

In the single-page version, a link to Section 5 (Coroutines) is https://docs.seastar.io/master/tutorial.html#coroutines - this is nice, because this link remains relevant if a new section is ever inserted before this section and sections get renumbered.

On the other hand, in the multi-page version of this link is https://docs.seastar.io/master/split/5.html#coroutines - note the "5.html" in the URL - this link will break if we ever add or delete or move a section.

The request (made by @avikivity) is to have htmlsplit.py name the separate HTML files by the section's name instead of number.

As we do for anchors, we should replaces spaces in the file name by hyphens (which according to Google's guidelines, is preferred over underscores).

CC @avikivity @tchaikov

@nyh nyh added the documentation Documentation - the tutorial, doxygen comments, etc. label Feb 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Documentation - the tutorial, doxygen comments, etc.
Projects
None yet
Development

No branches or pull requests

1 participant