[Q] How to properly create keywords using header styles?

[ivan-mogilko]

Trying to resolve this bug in the Editor I found out that the manual's index has some keywords in the wrong order, where e.g. "General settings" and other big titles cannot be found by auto search. On the other hand, it seems, some of the subtitles are displayed as if they were first-level titles instead.

An example of what I am speaking about:

Notice how "Android" is displayed as a first-level topic, but "Editor preferences" as a second level (should be first instead); or "Basic properties" displayed as a first level topic, but "General Settings" as a second level (should be first).

Comparing the pages which work with those that don't, it seems like the ## header should be used for a top level and ### for second level. Using # header breaks the keyword level in the index. Is this correct? I'd like to clarify this before making any edits and breaking things more.

[ericoporto]

Comparing the pages which work with those that don't, it seems like the ## header should be used for a top level and ### for second level. Using # header breaks the keyword level in the index.

@morganwillcock I think you already told me this a billion times but I forgot...

[ivan-mogilko]

I found this:
#96 (comment)

unfortunately this was never added to CONTRIBUTING.md

[ericoporto]

I think you are correct that it must be ## and ### but I don't remember why... I found my original GeneralSettings before I deleted and undo the splitting of SettingUpTheGame on the first time and it was using ## and ###... I just adjusted it. Need to find out which other pages I broke...

@ivan-mogilko in the old README it was here: https://raw.githubusercontent.com/adventuregamestudio/ags-manual/2aed2f7033bc93fc170c132cd69cc0ed48899129/README.md

Copied to CONTRIBUTING.md to here ->> https://github.com/adventuregamestudio/ags-manual/blob/master/CONTRIBUTING.md#indexing

[ivan-mogilko]

I think this is resolved.

[morganwillcock]

To create an H2 style heading without an index entry, use the alternate H2 markup.

I think this was because of how the Sphinx plug-in was working. For Pandoc I'm not sure there would be a difference between the markup styles: the metadata comes from the internal state after the Markdown syntax is read so there shouldn't be any difference.

[ericoporto]

I think this was because of how the Sphinx plug-in was working. For Pandoc I'm not sure there would be a difference between the markup styles: the metadata comes from the internal state after the Markdown syntax is read so there shouldn't be any difference.

@morganwillcock this means we could have deeper nesting of headers? Like H4 and lower? Is there any limits on what goes in the index and what doesn't ?

[morganwillcock]

It is technically possible but the current setup effectively restricts it to two levels, and those are set as H2 and H3.

For the CHM index, anything that needs to be looked up by the Editor needs to be at the top level, unless the linking process get smarter. So anything defining script syntax needs to only be at the top level. Anything else needs to keep the top level clear of anything that could cause name collisions with script syntax, and also not cause naming collisions between individual pages. Avoiding collisions is why sub-headings on non-scripting pages are a sub-item in the index but that means you cannot find the sub-headings alphabetically in the index.

## heading
    ### sub-heading 1
    ### sub-heading 2

So an additional level is possible but the increase in vertical space would probably make the scrolling of the index harder to use (too small a scroll-bar widget and too much motion per step of the widget).

For the website index there is no restriction needed at the top level and naming collisions are avoided by joining the main page title onto the end of the subtitle. This means you can find the sub-headings alphabetically.

### sub-heading 1 (## heading)
### sub-heading 2 (## heading)

The formatting here would need to be change to accommodate more levels.

So the current setup is generally to try and avoid problems for all use cases. I think a good solution probably needs to split the indices between scripting syntax and other content so that there is no confusion about what the entry is for, but the CHM viewer doesn't support that.

[ivan-mogilko]

The script keywords are all H3 level, yet they are in the first level index. Is it because they are additionally marked by quotes (e.g. script_function), or there's some extra trick?

[morganwillcock]

Yes, the first inline code element within the header overrides the header name and indicates it is describing a part of the scripting API.