The parser shouldnāt care about spaces there, so it doesnāt matter. There isnāt a style guide for documentation, but I donāt think this makes that much difference to the readability of the code.
I have the impression that capitalizing the keyword helps with reading the help source code since one knows what the tag is and what the text is. But maybe thatās just my eyes.
I agree with @smoge that capitalising the keyword helps when reading the help source. However, in the search result, there are fewer uppercase keywords than lowercase keywords. So it seems better to keep them all in lowercase. For typing, uppercase requires extra work, so it is not efficient for whoever is typing the text.
Argument:: and method:: have only a single word, so no space is needed. However, section::, subsection and subsubsection:: can have multiple words, so a space after these section tags improves readability, I think.
Iām new and donāt have a strong opinion on these things, but while I agree with those conclusions, I do think generally capitalizing keywords is a good idea, irrespective of the search results (Iām actually not sure what search results you mean here, I apologize if this is somehow obvious to everyone else).
Naively I would think that as long as the help parser doesnāt care, there seems to be no reason not to simply find and replace all the tags with uppercase (via regex or whatever), or does that risk creating more problems than it solves?
good pointā¦ although, having done some work in latex, my process there was usually to separate formatting from actual writing; that is to say, the work for which capitalized keywords would be distracting simply isnāt the same kind of work for which they would be useful. I think the issues addressed here are mostly of the āformattingā kind. I donāt suppose people who write whole new helpfiles from scratch do that in schelp files right away? But maybe they do. Just my two cents, anywayā¦
I think that conversation already happened in the past somewhereāsomething like including a schelp plugin for pandoc (wich can be written in lua or haskell).
For example, search results from the current build of the latest SC3.14_dev are as follows
method::
^method::: 5742
^METHOD::: 1556
^Method::: 2
classmethods::
^classmethods::: 469
^CLASSMETHODS::: 168
^ClassMethods::: 158
^Classmethods::: 1
emphasis::
emphasis::: 13
EMPHASIS::: 0
Emphasis::: 0
strong::
strong::: 97
STRONG::: 6
Strong::: 2
Lower case keywords are preferred.
I think upper case keywords are easier to read, but require the author to hold down the shift key. This reduces productivity.
Currently I have converted them all to lower case.
Using regexp does not always work:
Over the last few days I have noticed that the SC documentation is not consistent in style. Some of the guides and tutorials are written in a consistent style because they are written by one or two authors. However, much of the documentation is not and is missing punctionations, subjects. The first letter of the sentence or the first letter of the explanation is not uniformly capitalisedā¦ This is very difficult to organise.
Thanks, now I get it!
Actually, I forgot about code highlighting earlier, which does what uppercase keywords would do (i.e., visually highlight said keywords), only better (because non-permanently)ā¦ so this would be an argument in favor of the lowercase keywords (in addition to your already having converted them to lowercase).
I had, at one point, started on an org mode exporter for schelp, but I donāt remember what condition itās in. That was years ago and Iām moderately sure that I didnāt finish it.
Agreeing on any single rule, like whitespace after tag::, will be less likely to take root outside of a more comprehensive set of guidelines for SC docs.
An official style guideline is totally reasonable, and has been beneficial for the SuperCollider and C++ codebase IMO. They would provide a foundation for large-scale cleanup of the docs. They may even motivate someone to make a formatting/linting pipeline for it, and introduce syntax highlighting into the IDE for .schelp files.
A bulk of the effort for making guidelines is in drafting proposed rules and patiently shepherding the contributors over the finish line.
As an aside, I was able to sneak in a fairly wide cleanup of code formatting in help (Class) files, only because we have official guidelines on code. I didnāt touch other parts of the docs files because we donāt have agreed-upon guidelines and so would have derailed that effort.
EDIT: I see thereās a proposal to work on guidelines in another thread.