Code Styling Conventions about alan-docs HOT 5 CLOSED

I really don't like all caps. That's my preference, of course. But to me it is LOUD and in the way of the natural sentences that Alan code is supposed to be. No ONE write SENTENCES this WAY. (I know, noone writes random capitalized words inside sentences either...)

Especially if you have code highlighting I think keywords should not stand out to much.

I know that the ALL CAPS styling have somehow stuck since the 80's ;-) even if I try to be adamant about writing all my Alan code examples in Capitalized style...

I would prefer the capitalization of keywords in code.

In EBNF I agree to go for ALL CAPS, because that is the convention for most EBNF grammars I've seen.

(Why do you think EVERY is more natural than Every?)

And actually, I've used "object", "location" too, since they are not a keywords. It is a built in class, but there is no difference between a builtin class and one that a library defines or the author himself.

from alan-docs.

I agree 100% on the ugliness of all caps, but my consideration was focused on making it easier for the beginner to distinguish between keywords and native classes and custom classes.

(I know, noone writes random capitalized words inside sentences either...)

Exactly! the issue really boils down to aesthetics here, and I agree that capitalized is less intrusive than all-caps.

It is a built in class, but there is no difference between a builtin class and one that a library defines or the author himself.

The point here is that the examples in the manual are mainly out-of-context snippets, so the casing convention was just intended to make a clear distinction between native and custom elements. I was sharing some considerations from my own experience when I was first reading the various docs, and had found some of the Library documentation easier to sift through because of the all caps convention (especially when sifting through the document quickly, looking for examples).

But then of course syntax highlighting should be enough for this, as it would clarify by color what is what.

Ok, I'll then ensure that keywords are always capitalized in all examples (current and future).

from alan-docs.

I propose that Isa should be capitalized as IsA (I'm working on substitutions right now, and have come across this).

Similarly, Elsif should be ElsIf, and so on, where keywords that comprise multiple words should be capitalized as if there was a space between them (IMO, easier to read).

from alan-docs.

Good.

Since the syntaxhighlighting is in our (your) control, could we consider a separate highlighting for built in classes, to make that a bit clearer?

I know we can't be sure about how all backends would handle highlighting. I know that the trick I used for marking lines inside code segments in the guide did not come through to the PDF...

from alan-docs.

The current Alan syntax I created for Highlight already gives special color to builtin classes (if the user wants to "turn them off" he just needs to assign the same color as "normal" style to them).

I know we can't be sure about how all backends would handle highlighting.

I haven't yet found the time to look into it closely, but I do fear that some backends might object to it (definitely online services like GitBook and others). But chances are that there are workarounds for it.

In the worst case, I'll build an Alan definition for Rouge, the Ruby highlighter natively supported by Asciidoctor, and that should work with all backends.

Another trick could be to use the PP preprocessor and resort to macros to handle highlighting before feeding the source doc to AsciiDoctor, and have the macro produce format-specific raw blocks that AsciiDoc should just pass through (either HTML, XML, TeX, or whatever).

But I'd like to keep the whole thing simple, and as close to AsciiDoc standards as possibile, so looking into a new Rouge syntax might be best.

from alan-docs.