Styling Keywords as Inline-Code

[tajmone]

@thoni56, I propose that Alan keywords in paragraphs get styles as inline code, whereas in the manual they are currently styled in bold.

Example:

Using the Syntax construct, you can also define more complex player input.

becomes:

Using the Syntax construct, you can also define more complex player input.

In computer related documentation, this is becoming a standard way of formatting keywords, code snippets and verbatim text related to the terminal; it looks better and it's more intuitive to the reader.

The problem is how to handle cases in which keywords are printed with their plural form, like in:

For this purpose, we use Locations.

which could be rendered as:

For this purpose, we use Locations.

... where the "s" of plurality directly follows the inline-code. (in AsciiDoc must be formated as ``Location``s, with double backtick).

This is also seen frequently in documentation, although it might not look quite as nice. But in my opinion it visually reinforces the actual keywords spelling, and it also highlights how these are strictly related to natural language in their usage.

I'm not quite sure about their usage in headings though, as these tend to look bad in the final document — especially since many sections will contain keywords in their title, which would end up looking messy. So I'd rather exclude headings, and only apply inline-code styling to paragraphs, notes, and similar document elements.

So, if it's ok with you, I'd like to proceed and change all occurences of keywords in paragraphs (or other elements, except headings) from bold to inline code. I'd like to get these search-&-replaces tasks out of the way before starting to proofread the whole document, because once these are done with I'm going to split the document into multiple files (one for each chapter).

[thoni56]

This seems like a good step, and I agree that is more the way things are done now.
Also agree on the headings, leave them without inline code. Are they bold now? If so this could be kept, maybe that was your suggestione.

[tajmone]

Also agree on the headings, leave them without inline code. Are they bold now? If so this could be kept, maybe that was your suggestione.

No, I haven't come across any styling within titles. Also, keep in mind that headings are already bold, usually, so marking a word within a title in bold would achieve the opposite effect (ie, style it as normal) in most output formats (like in all italics paragraphs, where italic words are shown in normal, as sometimes is found in prefaces), while in other formats it would not achieve anything. This would depend on the document settings, but usually in word-like documents that is the default behavior, and it also frequently so in CSS styling of XML based documents.

[thoni56]

So, headings would have to use some different type of keyword highlight, then. Like quotes or italics...

Good that we don't have to consider this. At least not just now.

[tajmone]

Done:

• Commit 646332b fixes inline-code styling.
• Commit dca5c4b fixes IsA and ElsIf casing.

In the original text, often keywords where enclosed in single-quotes; since inline-code styling adds a good visual separation, I've removed the quotes in most occurences (except a few contexts in which they seemed due).

I'll think about a solution for keywords in headings. I've strugled with that in many documents in the past. Usually, I've opted to use some styling that wouldn't show up in the TOC, only in the actual heading. The problem might have to be handled differently in different output formats though, via custom styling.

Bold styling doesn't seem a viable option, as in most documents headings will be bold anyhow. Maybe resorting to colors could be a good solution (eg, having keywords differently colored in actual headings); again, this usually won't show up in the TOC, as that would be an autogenerated series of links, where most probably the style for links would apply to the whole entry, overriding custom colors (except for italics, which might show up in TOC styling).

On the other hand, bold styling using *...* could be used in the headings, and then controlled via custom stylesheets (eg, affecting color instead of text style).

I'll need to do some testing with these (haven't used AsciiDoc in the last 2 years, and I've got a bit rusty).

[thoni56]

Are there such headings? Otherwise we don't need to consider that special case. Unless for your own embetterment ;-)

[tajmone]

Yes, actually there are many, as keywords do show up in titles quite a lot. And probably readers would appreciate some visual clues to quickly sift through the TOC and spot the keyword they are looking for — after all, this is a reference manual, so after reading the whole book users will still refer to it often, and usually just to look up specific topics, so quick navigation of the document is important as often it will occur while the user is stuck with some compiler error message and needs to understand a real case problem. In similar situations, anything that helps quickly spotting a keyword in a page or in the TOC is going to make life easier for the end user.

If it's OK with you, I'll postpone this to a later stage. Having worked with book reprints for a number of years, I've developed a personal strategy on how to process documents. For years in a row I worked in "book reprinting": I would be either given old paper books (from the pre-digital era) and was asked to produce a digital document from it (Word, or ePub), with all styles, TOC, notes, etc., or a digital PhD thesis that needed formatting according to standards. When the ePub/Mobi formats first came out, and when eBook readers where being first marketed, there was a huge demand from publishers who realized that some out-of-print paper books could now be republished with no printing-costs, as eBooks (books that wouldn't be worth reprinting in paper, especially in Italy where the book market is not huge, and the language is not spoken elsewhere in the world).

So, usually I had to take an old paper book of 300 pages, scan it, OCR it and repage the whole document within a day! It might sound a very tight schedule, but after repaging 100 books you develop a methodology to go about the whole process. The hardest part is learning to proof-read the whole book working with both the digital and paper original, and not miss out any italic or bold words, punctuation marks, accented letters, letter casing, and other details that might get lost or corrupted during the OCR or conversion stage. But again, practice is the best teacher.

Keep in mind that rebuilding the Manual structure from the pandoc converted document only took me a
couple of hours; which also means that until I get to the stage where I actually proof read the whole manual from beginning to end I'm basically just working with search-&-replace global substitutions, just in order to get out of the way most occurences of any kind (and, of course, there is always something missed out in the process, but it will be catched later on).

Mostly, I work with RegEx substitutions, but these must be applied in a specific order, because in lightweight markup formats like AsciiDoc and Markdown the presence of formatting symbols like * and _ end up interfering with search and replace operations, and I might miss out some contents. For example, this was the reasons I postponed converting curly quotes to Asciidoctor styled smart quotes (the backtick enclosure makes searches more complex), and why I wanted to finish a certain group of substitutions before splitting the document into multiple files.

I think the best approach would be to first focus on

1. blocks-styles reconstruction (notes, quotations, admonitions, verbatim blocks, etc), rebuild all the cross-references lost in conversion, and also the Index; check/fix tables (and their styling); then
2. proof-read the whole document from beginning to end (which is a good chance for me to read the whole manual again, but in a more focused way), and finally
3. start to look at custom styles, syntax highlighting, and other customized document settings.

I think that keywords in heading might be worth styling, but also that in some document formats it might be better to hide that style. For example, if you end up making the manual available in paperback format (via Print-On-Demand services, like Lulu), or create a printable version of the PDF, in those documents all color styles should be rendered as black, for better printing results (maybe some elements could have a light grey background, like notes and admonitions, but usually they don't print well on paper, and they prevent photocopying the paper document).

I think that making the Manual available in paperback would be a good idea, as many people prefer paper books to digital documents. With POD services like Lulu you can easily do that without costs, as the book is printed and bound at purchase time. You might sell the book with no profit margins, or take a small profit to sustain the Alan project, as you wish; but making the book available in printed form is a good service to end users, especially to IF fans who love to collect physical items (and there aren't many of them left in the digital era).

[thoni56]

Again, impressing.

Of course, keywords would be in the headings, especially when it comes to the section explaining something about that concept,.

I concur with the approach, also when it comes to leaving formatting of keywords in headings to late in the process.

[tajmone]

All-Caps Keywords in Headings?

Following the same reasons for Keywords in Index proposed in Issue #5, it might make sense to use all-caps casing for keywords in headings, instead of using font styles, colors or inline code.

While all-cpas keywords might look hugly in the normal text, headings could be an exception:

1. Headings are both title-cased and in bold, which somehow mitigates the loudness of all-caps keywords.
2. The occurence of keywords in headings usually boils down to one, maximum two keywords per title, so the overall impact shouldn't be too bad (at least in the document body, while on the TOC it might have more impact, but the TOC is not intended for consultation, not for reading).
3. The resulting TOC would be much easier to sift through and spot keywords, as these would stand out more, which is probably what most readers eager to find quickly a given keyword might wish for.

As Issue #5 already points out, it's unlikely that we'll find a unique styling convention that could cover all contexts, so having separate styling conventions for the main body of text, the Index and headings might be a viable solution and compromise — after all, each of them is a context of its own, with different rules applying to each, and keywords casing might be one of them.

Here is a selection of entries from the TOC, and how they would like with all-caps keywords:

INITIALIZE

DESCRIPTION

Articles and Forms

Articles

Form

Printing

MENTIONED

Container Properties

LIMITS

HEADER and ELSE

EXTRACT

Verbs

ENTERED

Verbs

META Verbs

Verbs in Locations

Verb Checks

DOES-clause

Statements

Output Statements

String Statement

STYLE Statement

DESCRIBE Statement

SAY Statement

LIST Statement

Multi-media Statements

SHOW Statement

PLAY Statement

In some cases (like "Form"), where the keyword and its English noun counterpart overlap in meaning, keywords could be treated like nouns and follow natural casing instead. In entries like "PLAY Statement", it makes more sense to emphasize that "play" is a keyword.

For the same reason, I'd rather avoid "VERBs in LOCATIONs", for such titles don't need to be seen as keywords.

Unfortunately, when it comes to programming languages documentation, it's quite common the need to compromise on aesthetics for practical reasons, as technical issues and the search for a standardized notation tend to prevaricate on elegance. Most likely, we'll have to face some choices weighing the pros and cons of aesthetics and practicality, keeping in mind that the Alan documentation is likely to be read and consulted over and over during the learning stages, so IMO priority should be given to intuitive contents presentation and ease of use on the end user' side (quick information retrival and accessibility through styling conventions being one aspect of it).

But of course, it's just a suggestion, and what matters is finding some convention to stick to so the final Manual will keep a uniform styling (hopefully, the same conventions could be applied to all related documents to).

[thoni56]

Agreed that All caps KEYWORDS in HEADING ;-) is a reasonable trade-of that works.