Programmatic styling of INFO/IMPORTANT/TIP

[AlanDrake]

Applies extra styling to the INFO/IMPORTANT/TIP paragraph blocks (but not the old ones with the image icon).

The substitution happens at runtime via javascript.

I made NOTE violet because blue is too soothing and safe, users might gloss over it.

[ericoporto]

This is interesting but I feel we need to fix #96 . I will take a look at that and comeback to this.

[morganwillcock]

My initial feeling is that any sort of insert or rewrite of the document structure should be done before the page is written (the existing filters do it and to support syntax highlight in indented blocks it also needs to happen), although for optionally wrapping a class around a paragraph I'd have to check whether it looks feasible. It looks good though.

[AlanDrake]

Consider the javascript a temporary solution until someone who knows lua can make it happen.

But there's the question of format...

Are we going to keep the current format?

**NOTE:** Note text

Use one of those other standards (if we plan to migrate to docsify/docusaurus/vuepress/etc.)

:::tip
This is a tip
:::

Or even the new beta github ones (only Note and Warning) which use blockquotes:

Warning
Experimental feature

> **Warning**
> Experimental feature

[morganwillcock]

Technically we are already using GFM for the table support. If the blockquote ones are legitimately going to be part of the GFM specification then in theory the GFM Pandoc reader would support it and we don't have to do anything to detect the blocks. That might take a while to happen though, or possibly the implementation of the reader wouldn't allow it happen.

Everyone just invents their own so there probably isn't a wrong choice:
https://learn.microsoft.com/en-us/contribute/markdown-reference

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Since the choice of Markdown was to make the page editing easier and to avoid a sea of markup directives, personally I'd just stick with the one that looks most like an actual sentence:

**NOTE:** Note text

...but presumably that doesn't allow a multi-line note.

It is probably worth bearing in mind that for better indexing the same issue may come up for indexing directives, say if you want to index a position (e.g. heading) within a page rather than the page itself. In the long term, I'm not adverse to using a different document format altogether. Other than the one person who rewrote the tutorial (thank you!) and occasional minor changes from a couple of other people, having the pages be directly editable as a GitHub Wiki didn't really yield any huge benefits. Not to say it wasn't worth trying, and there was no improvement.

[AlanDrake]

...but presumably that doesn't allow a multi-line note.

It's actually possible, by using <br> or \ at the end of the line, so it becomes a new line and not a new paragraph.

having the pages be directly editable as a GitHub Wiki

Speaking of which, we really should add an "Edit on github" link. The effort of having to manually locate the corresponding page might be a turn off to normal users, and also an inconvenience to us.

https://github.com/adventuregamestudio/ags-manual/wiki/${filename_without_ext}/_edit

[morganwillcock]

Speaking of which, we really should add an "Edit on github" link. The effort of having to manually locate the corresponding page might be a turn off to normal users, and also an inconvenience to us.

There wouldn't be any guarantee the two are in a similar state. In the worst case the link points to a page that doesn't exist (and maybe tries to recreate it?).

[AlanDrake]

In the worst case the link points to a page that doesn't exist (and maybe tries to recreate it?).

They should see a 404 page, so there should be no risk of recreating it.

As for the pages not being in similar state, perhaps the web manual should always be rebuilt?

But... the wiki has a drawback that it can't be branched, right? So when we get to ags4 and perhaps want to keep a second branch with the old manual, we won't be able to unless the page files are part of the branch itself.
We should start thinking how to handle different versions.

[ericoporto]

having the pages be directly editable as a GitHub Wiki didn't really yield any huge benefits.

I think this is false, have you checked our revision history???

the wiki has a drawback that it can't be branched, right?

It's just a different interface to a GitHub repository, you can branch it, but it won't offer a visual interface, but locally it's a git repository with branches and everything.

See also my previous comment.

[morganwillcock]

As for the pages not being in similar state, perhaps the web manual should always be rebuilt?

I specifically stopped it doing that because people made changes that caused a build failures. And that was when it would build natively on Windows. When a new commit went in the build system I would then have to fix other people's edits because no-one else was checking anything.

But... the wiki has a drawback that it can't be branched, right?

I think we had looked before and it could be branched, as at heart it is just a git repository. I think the problem is that the GitHub web interface doesn't give an branch access.

So when we get to ags4 and perhaps want to keep a second branch with the old manual, we won't be able to unless the page files are part of the branch itself.
We should start thinking how to handle different versions.

Both the broken edits and the branching of manual content were reasons why the build system was changed. There will be some context on the reasoning here: #159

TLDR: The build-system can now branch to use a different sub-module for the source of the pages, the source pages can be anywhere (go back into the regular ags repository branches, if required), the source pages are incorporated into the release to stay in sync with the build-system. The "approved link" link is a sign of a problem and could now be removed, because someone with commit access needs to explicitly update the source reference for the manual pages.

Also, this needs to be taken down to avoid confusion about which manual is current: https://www.adventuregamestudio.co.uk/manual/

[morganwillcock]

having the pages be directly editable as a GitHub Wiki didn't really yield any huge benefits.

I think this is false, have you checked our revision history???

git shortlog --numbered --summary
   295  Morgan Willcock
   232  ivan-mogilko
   211  Érico Vieira Porto
   125  selmiak
   120  Ivan Mogilko
    49  Érico Porto
    45  e
    43  ericoporto
    36  Scummbuddy
     5  AlanDrake
     4  Vikram1323
     2  Benjamin Penney
     1  BootsManOut
     1  Bálint Magyar
     1  Mariusz Klimek
     1  Steve

Scummbuddy did the tutorial, I think those and Selmiak's edits are the significant changes we wouldn't have had if not for the GitHub wiki. I don't think we should count ourselves.

[ericoporto]

The edits on my GitHub username are mostly on my phone, using the GH wiki interface. The complex ones I have an additional repository to help here: https://github.com/ericoporto/ags-manual-wiki

I think the wiki is useful but if we would use a github repository it could be synced without much effort. I would not skip having a web interface.

by using <br> or \ at the end of the line

@AlanDrake , there's also two spaces at the end of a line ( ). We use it in some places like the credits page and some other random places throughout the manual. This is the most common new line without new paragraph I see on other markdown documents in GH.

---

Overall, I am a bit lost on the discussion here, I would prefer to just get the format documented somewhere before adding this. Unfortunately we haven't done that yet.

[morganwillcock]

It doesn't seem easy to dynamically add a class in a filter. I think the best I can do is someting like this, which is a bit hacky:

local List = require 'pandoc.List'

function Para(elem)
  local class = nil
  local first = elem['content'][1]['text']

  if first == 'Important:' or first == 'Note:' or first == 'Tip:' then
    class = first:sub(1, -2):lower()
  end

  if class ~= nil then
    return List:new({pandoc.RawBlock('html', '<p class="' .. class .. '">'),
                     pandoc.Plain(elem.content),
                     pandoc.RawBlock('html', '</p>')})
  end

  return elem
end

...this currently expects the first word to be unstyled:

echo Important: **Test** paragraph | pandoc.exe --lua-filter lua\insert_style_classes.lua
<p class="important">
Important: <strong>Test</strong> paragraph
</p>

echo Note: **Test** paragraph | pandoc.exe --lua-filter lua\insert_style_classes.lua
<p class="note">
Note: <strong>Test</strong> paragraph
</p>

echo Tip: **Test** paragraph | pandoc.exe --lua-filter lua\insert_style_classes.lua
<p class="tip">
Tip: <strong>Test</strong> paragraph
</p>

I'm not adverse to using that as the format if the goal is to keep markup to a minimum.

It is also possible to use stringify on the first element instead of reading its text value. In that case it would match Note: or **Note:**, but would not match **Note**:. I'm not sure allowing variation is a good idea, and detecting only **Note:** by itself is probably pretty complicated, the data accessible within the paragraph element doesn't indicate exactly how each sub-element is styled.

I'm also not sure that adding the class directly to the paragraph is a good idea? I'll defer to someone else about whether anything I've written here is a good idea, and equally I'm happy to just use the JavaScript transform until the status of the GFM specific syntax is better established.

[AlanDrake]

Adding the class to a container and trasforming/replacing the opener text is the necessity, doesn't really matter if it ends up as a p a blockquote or a plain div.
If you feel the lua is too hacky, we can keep the javascript until a future format change.
I'm good with regexes, so performing massive changes when formats are consistent is not too much a burden. Admonitions have been streamlined, so if you want to try other formats just let me know.

[ericoporto]

@morganwillcock I am fine with merging this, but I am unsure if it's necessary to merge the other branch before this (am a bit lost on the discussions)

[morganwillcock]

I think the changes are all independent, so if Alan says it is ready it should be good to go.

[AlanDrake]

Alright then, let's merge it.