Rename source files for the appendices for the manual to letters
thoni56 opened this issue · comments
Problem
It is a bit hard to quickly find the asciidoc source for an appendix, and actually also for a chapter if you don't know by heart what the content of all the chapters are.
Description
Currently all manual "chapter" sources are numbered sequentially.
A strategy to make it easier to find the source for an appendix might be to name the appendix source files as manual_<letter> where <letter> is the character for the appendix, e.g. manual_A.asciidoc would be the source for appendix A.
An even bolder step would be to give all the sources a single word "post-fix" indicating the content. E.g.
manual_01_intro.asciidoc
manual_02_concepts.asciidoc
manual_03_language.asciidoc
manual_04_lexical.asciidoc
manual_05_running.asciidoc
manual_06_hints.asciidoc
manual_07_construction.asciidoc
manual_a_using.asciidoc
manual_b_interaction.asciidoc
manual_c_runtime_messages.asciidoc
manual_d_grammar.asciidoc
manual_e_words.asciidoc
manual_f_compiler_messages.asciidoc
manual_g_localization.asciidoc
manual_h_portability.asciidoc
manual_i_copying.asciidoc
Would such a rename trash any functionality on some toolchain we are using?
It's a good idea. I'll do it tomorrow afternoon.
@thoni56, I've done the renaming work, but directly on the dev-man branch for I wasn't sure if trying to rebase on master after renaming files would work out. So, we shouldn't be doing any more contents tweak on master until the dev branch is merged again — in any case, I think we shouldn't update the master branch ever, but just postpone any edits to next release.
As for the Glossary, I've renamed it using a z, instead of j, because it's not an appendix and it should always come last, even if we were to add a new appendix to the Manual.
Thanks!
we shouldn't be doing any more contents tweak on master
My thinking was previously that only the addition of documentation of new features was done on the dev-man branch and thus in sync with the feature growth in snapshot builds, and that other improvements (spelling, clarifications, ...) should go directly into master to provide immediate benefit to manual readers because it would still describe the latest release. Then the merge-points would coincide with new releases and the change in "released" documentation would only be that functional change.
But seeing the problem we get when rebasing I tend to agree with you. At least until we have found a way to do smoother rebasing. (I was hoping that rebasing the dev-man branch on top of new commits from master would be a no-brainer, but it does not seem to be... I haven't actually thought about why that is, have you?)
But at some point we have to start doing impovements on master, because in the event releases of Alan will come more seldom, we don't want to have a lot of good improvements "blocked", waiting on dev-man branch for a release that might be long in the future. But let us ponder on this further as we go.
Personally, I think that it's not worth keeping the dual standard, after all the Alpha version is available for live preview too.
But at some point we have to start doing impovements on
master, because in the event releases of Alan will come more seldom,
The Alpha branch usually contains bug fixes, new features like the apostrophe elision or the block comments are rather rare, and usually call for a new Beta release as soon as possible. So, unless there are new features in the Alpha version, we can always decide to merge it into master (keeping the same Beta version on master). On the other hand, if there are new features, why not make a new Beta release?
In the past trying to keep the dual standard has provided more headaches then benefits — mostly because there are some natural time-lapses in which we don't work on the Manual, and end up forgetting what was done where.
Personally, I don't think that the average user would miss a lot if a Beta release of the Manual is delayed, unless he/she's an advanced user — in that case, why not peek at the Alpha Manual preview? (as well as Alpha SKDs too)
The main problem with the dual standard is that if we need to rename source files (e.g. because adding a new chapter/appendix, or changing the book structure), than rebasing might fail. Git doesn't do a too great job at tracking files which were both renamed and edited in the same commit. Also, I have no idea how (and if) rebasing is possible in such cases — because the commits we'd be trying to rebase would have different file names now, which might not be a linear operation.
Apart from this, rebasing should always be possible in other context (i.e. other docs being edited, or the toolchain). We only need to keep separate the type of contents we edit on the dev branch (usually only AsciiDoc sources, book images, etc.) and what we edit in master instead (e.g. the toolcahin) and rebase the dev branch on these changes.
Totally agree with you here, actually. Like you hint at, the goal should really be to minimise the gap between the beta's and the development snapshots (of the complete Alan system) by making it easier and quicker to make a new release. Although that is completely true, I still hesitate to build a new release because of the manual work involved it is (historically has been). Which of course means that I should look for more automation ;-)