10

At the moment, the Syntax field in documentation examples is limited to a list of one-liners, and nothing else is allowed. Unfortunately, this includes formatting tags, such as versioning tags (e.g. <!-- if version [gte C++11] --> and <!-- end version if -->). Due to this, applying versioning to the Syntax field is more awkward than it needs to be.

Ideally:

- Syntax
- Syntax
<!-- if version [gte C++11] -->
- C++11-or-later Syntax
- C++11-or-later Syntax
<!-- end version if -->

Ideal example, as it would appear live; rendered as image, because I don't know how to make meta SO format it this way.

Unfortunately, this isn't allowed, and gives the error message Syntax must be formatted as a list of one-liners. Due to this, the best that can currently be done, to my knowledge, is something like this:

- Syntax
- Syntax
- // C++11 or later:
  - C++11-or-later Syntax
  - C++11-or-later Syntax

The above example, as it would appear live; rendered as image, because I don't know how to make meta SO format it this way.

I feel that this is an abuse of the list formatting used for Syntax, but I honestly can't think of any other way to indicate that some syntax is version-specific. As such, I would like to request that versioning tags, and perhaps other, similar formatting tags, be allowed, as long as the actual examples still use the appropriate list formatting.


Also see:

3
  • I also find it difficult to create code blocks in the Syntax section, due to code-block-formatted list items breaking & trying to put everything on one line, but that can be awkwardly worked around by making each line a list item, and indenting it appropriately; unfortunately, this causes issues with the closing } brace, which will be about 2 lines lower than it should be. This is much less important at the moment, though. Commented Aug 29, 2016 at 18:18
  • I'm still trying to figure out what the real purpose of this "Syntax" section is, and would prefer not to add complexity to it until we figure that out. It seems to me that anything it offers would be equally or better solved by the "focus"/"introduction" section that is coming soon.
    – Cody Gray Mod
    Commented Aug 30, 2016 at 7:20
  • @CodyGray That seems useful. I imagine a short description would go in "Focus"/"Introduction", and Syntax could be used for a short demonstration of each example's syntax (if possible). It'd be a lot cleaner than Syntax being "sometimes it's code shared between multiple examples, sometimes it's the actual syntax, sometimes it's even a moose!" ...At least, that's my guess at how it'll end up playing out; guess we'll see when they release more information. Commented Aug 31, 2016 at 0:54

0

Browse other questions tagged .