Revamping the manual's chapter 5 #1794
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Lots of repetitions on where SILE looks for files - Some rewording needed (e.g. packages vs. luarocks modules) - Example updated (lilypond.sile is non-working currently, switch to markdown.sile as the latter is already mentionned in chapter c02.
Frankly, it doesn't help and we can be more direct here.
The frightening sentence is better suited for a footnote... How to publish modules looks better when we say where to look for them.
Omikhleia
commented
Apr 30, 2023
alerque
requested changes
Apr 30, 2023
Incl. minor rewordings.
Co-authored-by: Caleb Maclennan <caleb@alerque.com>
Item from sile-typesetter#1351 (low-hanging fruit)
Item from sile-typesetter#1351 (low-hanging fruit)
Another item from sile-typesetter#1351: Remove undocumented chormode.lineheight setting. Its 4mm default where dubious anyway... But it turns how there was other problems: - Hook chordmode:chordfont was not applied where expected - A proper line height computation is likely what one would expect so as to avoid overlaps with previous content...
Item from sile-typesetter#1351 It can be both correct and less technical for casual users!
10 tasks
Re-organizing the topics in dedicated sections, we lost the big dichotomy from earlier versions of the manual, between main packages (that were sorted alphabetically) and experimental packages (a unsorted and actually non-curated list of things that range from usable to broken...). We can do better, with a nicer 3-level indicator: it's neat, not too intrusive, and respectful for the readers as to what they may expect.
I would have done without it sometimes: it's often filler text... BUT the default book class CAN break a page between a section heading and an immediate subsection heading, and this IS bad-looking when it occurs.
Avoid mentioning too explicit paths as they may differ depending on the installation process and the distribution.
alerque
approved these changes
May 25, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I think we can improve this chapter, fix some incorrect or unclear statement, remove/merge redundant details, and overall propose a better documentation structure.
Moreover, while at it, closes #1351