Comments (6)
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.
from alan-docs.
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.
from alan-docs.
Changes in PR #126 seems fine to me.
from alan-docs.
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.
from alan-docs.
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
from alan-docs.
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.
from alan-docs.
Related Issues (20)
- Switching to the Rouge Highlighter HOT 10
- ALAN Manual Is Not Highlighted
- MANUAL: Fix MESSAGEs
- Describe how nested containers are (not) handled wrt. limits HOT 1
- Post-Rouge Updates
- Add Conversion Guide to Website HOT 2
- HLJS: Missing Alternative ALAN Themes
- Highlight ALAN: Add Block Comments Support HOT 1
- Highlight.js ALAN: Add Block Comments Support
- XSL FOP: Missing Alternative ALAN Themes
- Update document preamble for the manual HOT 6
- Manual: Explain VERB Definitions With Multiple IDs
- ALAN Manual: Update to Beta8 HOT 8
- Mention How the AGAIN Message Is Tied to VISITS HOT 3
- ALAN Manual: Update Swedish List of NOISE WORDS
- Sass Themes: Fix Operators Colouring HOT 1
- Revise Ch 5. Running An Adventure
- Spurious Diagram Images in 'published' Branch HOT 1
- Adopt New Official Extensions for ALAN3 Solution and Transcript Files
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from alan-docs.