ALAN Manual: Add Parts & Make Code Prose-Cased
tajmone opened this issue · comments
@thoni56, there a couple of fairly radical changes that I've been wanting to do to The ALAN Manual, and now would be the right time to carry them out since the Beta and Alpha branch are aligned:
- Split the book in Parts.
- Convert all code examples to prose-case.
- Remove the trailing
_from the autogenerated anchors.
As for the Parts, based on my experience it will look much tidier than it does now, where we have these enormous chapters, which have too long numbering sequences, and make the TOC look cluttered.
I could work on this on a dedicated branch, and if we like the results than we merge it — and I'm sure it will look better, because I've done this with other books too.
The only important thing is that until it's ready there should be no changes to the manual alpha branch, or it would be very hard to rebase it after!
As for the prose case ... I know, I KNOW! You did warn me, when I was insisting to use SHOUT CASING! But after having worked at the new Foundation code, and its examples, using prose case, I'm starting to love it. And, thanks to the new Rouge highlighter we have all special words coloured properly now, so the reader will be able to discern what is what in the code even without keyword casing.
As for the _ in the anchors, I just find it annoying and I don't know why it's the default. But since we'll be adding custom anchors in the book, along with those autogenerated for the sections, I'd like them to be without the initial underscore.
So, if you give me the green-light, I'll start working in a dedicated branch on these changes, one at the time. But I'll need the Alpha branch to be left alone until it's all merged and alpha has been rebased.
Reference Links
You have my green light ;-)
I agree that these are good changes, and I`m not planning to do any updates. I won't be working on Alan until Christmas holidays, at least. And I'm sure we can coordinate, especially if you can merge back each change as you are "done" with them. So, go ahead, I'm looking forward to it.
You have my green light ;-)
Great!
I won't be working on Alan until Christmas holidays, at least. And I'm sure we can coordinate, especially if you can merge back each change as you are "done" with them.
They should be ready and merged by then!
Reviewing Pending PR
@thoni56, before starting working on Parts I should really squash and merge the changes from PR #126 first, so they don't get lost due to excessive conflicts later on, since the partitioning will involve also files renaming.
If you could just quickly review PR #126 and let me know if the changes are good to go, I'll then take care of squashing them into a single commit and recycle the text of the PR's pending tasks into an Issue for the future.
Most of the changes consist in annotating pending tasks via comments, removing obsolete comments, and some minor aesthetic fixes, etc.
But there are also a couple of significant rephrasing changes, and the ASCII workflow scheme being turned into a plain list, which might be worth looking into, just to make sure there are no alterations to the intended meaning.
Changes in PR #126 seems fine to me.
Multi-Part Book Preview
OK @thoni56, I've managed to split the book into Parts and pushed it to the manual-multipart branch, so to preview the results you'll have to checkout the branch locally and build the HTML and PDF books locally.
The book now looks much tidier, without all those excessive section numberings piling up. On the other hand, the number of Chapters has gone up significantly, since the introduction of Parts has rendered what used to be Sections into Chapters. So we have 58 Chapters in total now.
AsciiDoc preserves Chapters numbers across book Parts, there's no way around that (i.e. can't reset to Ch.1 at each Part).
Online Chunked Edition
You have to consider these changes in the light of the upcoming multi-part chunked online edition. I've already finished working on all the scripts and tools to publish the online version of the ALAN Manual as a multi-file book, split by chapters.
To get an idea of what it's going to look like, have a look at another book I've just published using this system:
I'll be using the same scripts and custom tools to create the ALAN Manual version. My idea was to provide a chunked version for online reading (at least for the Beta version), and the single file edition for download. Or something similar, we'll discuss the details and the pros and cons.
Partitioning Revisions
Now that we have a multi-Part version of the Manual, we can see in a clear way how the book is "balanced", i.e. which Chapters are very long and which are too short, etc.
The fact that we have so many chapters is probably a symptom that in various places there are correlated chapters that should be grouped under a single chapter instead.
Of course, Part II: Language Reference is the core of the Manual, and it's somehow bound to be a very long part due to it's technical nature, so there isn't much we can do to balance this out.
The book is now split into these Parts:
- Part I: Concepts
- Part II: Language Reference
- Part III: Lexical Definitions
- Part IV: Running an Adventure
- Part V: Hints and Tips
- Part VI: Adventure Construction
- Part VII: Appendices
NOTE — I opted to group all Appendices under a dedicated Part, instead of having them loose as top-level entries (which would be the default in AsciiDoc), since when we'll have a foldable TOC in the HTML document, this would make the TOC less invasive.
But bear in mind that we could also annex Appendices to specific book Parts if we wish to do so, instead of having them all the end, which would allow us to keep all Appendices within their relevant book Part, if this is of some advantage (haven't really looked into it, so I have no idea how they would end up being organized).
I was wondering whether some of these Parts might be grouped differently.
E.g. we could have a "Working with ALAN" Part, under which we could gather all chapters on how to use the compiler, interpreters, setup an editor, etc.
The "Hints and Tips" part could be assimilated into the "Adventure Construction" Part, since they are related topics.
Of course, these proposal are in consideration of how the Manual could grow in time, but probably some current Sections and Chapters could be moved around in the newly proposed arrangement.
When I was studying book publishing, I remember a book that taught how to check if the titles of each part, chapter and section were well formed. The idea was that each title should convey in a clear manner the author's intention, and what the reader can expect from the Part/Chapter by just looking at its title. In technical documentation, the advice was that each title should be a full sentence, with subject and predicate.
E.g. take "Part I: Concepts"; it's fairly vague. A better title could be "Basic IF Concepts" or something clearly communicates the gist of what that Part is all about. This would not only better guide the reader along the (fairly long) reading journey, but also provide maintainers with a solid framework to decide what goes where.
I'm just suggesting that if we wanted a chance to look at the Manual with a birds eye view, and reconsider some of its partitioning and titling aspects, now would be a good time do so, since the Beta and Alpha branch are fully synched right now. It's not unusual to do this, after all software documentation tends to grow by incorporating new feature as they are introduced in the software, so now and then it's worth considering if these added features require for some better reorganization of some chapters and sections.
Somehow, I think that right now the number of Parts is excessive. I have the impression that the book Parts should mirror the different aspects of how ALAN users are going to tackle with, which IMO are more or less:
- Learning the language
- Learning the tools
- Learning how to author adventures
The language part is definitely where the technical aspects of the "ALAN Language Reference" belong, which is a sort of book on its own, so to speak.
Anyhow, these are my impressions and consideration. I'd like to hear from you your views on the matters, and if we can do anything to improve the Manual and begin looking into new expansions of the book to improve its usability I'd be happy to invest effort in it.
Ready to Merge!
OK @thoni56, the partitioning work is done and ready to merge (unless we want to further reorganize the material).
The only point left to decide is whether to show the Part signifier or not next to the Part number and titles.
In the DocBook/PDF edition, both the Part and Chapter signifiers are always added, there's no way to change that unfortunately.
In the HTML backend we can decide whether to show or not the Part and Chapter signifiers. Currently, I've enabled "Part" and omitted "Chapter" (as it used to be), via the header attributes:
:part-signifier: Part
:!chapter-signifier:But of course, we can change that at any time.
If we omit the "Part" signifier, Parts would be shown only with their number — e.g. "I: Concepts" — which I don't really like, it looks odd, especially with Roman numerals.
I opted to keep the full "Part I: Concepts", but then the added "Part" signifier also ends up in the TOC, which eats up quite some space when the TOC is shown in the sidebar, which might cause long title to wrap — not a huge issue, but in the TOC having just the number would have been better.
There doesn't seem to be a way to control separately how the Part and Chapter signifiers are displayed in the doc and in the TOC, the same setting applies to both. We can control how the reference signifierss are shown in cross references, by either adopting their full spelled out version, or their abbreviations, but we'd already settled for using :xrefstyle: short, and providing briefer custom signifier only for Sections (i.e. Sect.) and keep the full signifier for "Chapter", "Appendix" and (now) "Part":
:section-refsig: Sect.I think that's fine, since only Section is worth shortening, the others look good. Also, we often customize the XRefs as needed in the book, e.g. when we'd rather show the section title instead of its reference number.
The main question is whether we should have "Part" shown next to each Part title (which looks nicer), at the price of having it in the sidebar TOC (which looks less nice) — for me it's OK as it is.
Bear in mind that the signifier doesn't necessary have to be Part, it could be anything we like — e.g. Book ("Book I.Concepts", etc.) or anything else that comes to your mind.
Other than that, and if you don't see any urgent changes to be done before merging, I'm ready to squash/merge the new partitioned book if you give the green light. We can always take care of details later, but since this changeset involved files renaming, I want to be sure that at least we're OK with the current parts divisions and their associated source files.
AsciiDoc Reference Links
I think your reasoning is fine. So I'm ok with the merge. It will be interesting to work with the new "format".
I also like your thinking w.r.t naming the parts and re-grouping, but we'll have to thing about that more. If we find a particular topic that should be moved we can do that and see where that takes us.