It is easy to add new fields to the admin page for the an article / category. More complicated is the script that actually turns this into fill_help_table.sql. If we want it to run as part of the KB I can write it to directly access the database and generate the content, otherwise I can make the needed data available via json.

The creoleparser we use has a method of exporting to text which is fairly good about what it strips and what it leaves. We can change this as needed.

For deep linking variables, we possibly could surround variables or other content in a macro and assign a keyword that way? We would have to discuss exactly how this works.

I'd be happy to work on this, I just need to sort out with Rasmus when I can do this. Unfortunately I have a decent queue of items in front of me at the moment.

OK great. If adding new fields is relatively trivial, and you're happy that's the best way to go ahead, then feel free to go ahead and add these - it'll take a while to correctly tag everything in the knowledgebase, and I can get started with that in the meantime.

Adding a macro around each variable description would work, but it would be quite tedious to add for every variable. What about getting the script to use the table on https://mariadb.com/kb/en/mariadb/documentation/variables-and-modes/full-list-of-mariadb-options-system-and-status-variables/ - all variables will always be listed there. If we want to add more descriptions that are parts of other pages later (I can't think of any besides the variables for now), we could add this to the script rather than tag on the knowledgebase.

A final issue is linkrot. At the moment, the KB gracefully handles page renames, but can't handle cases where variables may move. For example, the sole OQGRAPH status variable sits at https://mariadb.com/kb/en/mariadb/documentation/optimization-and-tuning/system-variables/server-status-variables/#oqgraph_boost_version If, in the future, there are more OQGRAPH status variables, these will move to their own page, and the URL will change to something like:
https://mariadb.com/kb/en/mariadb/documentation/storage-engines/oqgraph/oqgraph-system-variables/oqgraph_boost_version

This has already happened on some of the KB pages, and as more forums and external sites, along with the MariaDB client HELP, link to our KB, it would be good not to lose these. Is there a way to do this currently? If not, perhaps either the table or macro around the subsection idea could also be used to maintain these links.

Hi Ian,

Unfortunately I am not going to be able to work on this for a little while. I have some other projects that Rasmus wants to take priority.

I think I should be able to tackle this middle of October.

Hi Bryan, any news on this one? If you're too busy, I can take a look at it, but will need help with access and adding the new fields to the KB.

No news until you reminded me. I had a few things come up that took my attention.

I'm going to start this just by adding the new fields and seeing where we can go from there. Instead of adding the fields to the nodes I'm actually going to create separate tables so we have more flexibility and this can be developed / updated without impacting anything else.

For the main table I believe we would need:

• Node (links to the node)
• Category
• Keywords

Do you want me to just pull the list of categories from mysql.help_category or do you want to manage this through the admin interface? Same thing with keywords.

bryan, doesn't KB already have it? It has links and categories already. Keywords — I'd say it has them too, that's what search prompts show.

On a more general note, instead of export from KB to help tables and to any other format separately, it'd be easier to export the manual pages from KB to, say, docbook. And all other formats can be generated from it. Only one conversion from KB. And more consistent output in all generated formats, whatever they can be in the future.

All the data is there, but it isn't linked in a formal way where we can generate the help files I don't believe. We need a way to mark which articles should be exported. While we can re-arrange the KB as needed what we want for the help files might be different then what we want for the help database.

As far as the exporting goes, my plan was to just export title and text contents so Ian can handle the rest but if we can easily do docbook that sounds good.

I seem to remember that Daniel was also working on the reverse, using docbook content to generate KB content. I'll ping him so that he can give input just to avoid any duplication.

There are regular requests for documentation in pdf and other downloadable formats too, so solving this in one consistent way would be great.

But at the very least as Bryan says there does need to be a way to mark that content should be in the help contents.

I would prefer to manage things from the admin interface rather than just using the mysql categories, as these could be improved or changed in future.

Be sure to take note of the point above about including variables though, that's an important point. I would really like to be able to type "HELP aria_block_size", for example, and only get content from https://mariadb.com/kb/en/mariadb/documentation/storage-engines/aria/aria-system-variables/#aria_block_size section. That would be a big usability gain.

Okay, so I'm going make a new admin section for the help tables. In addition to the table I described above I'll make category and keyword tables populated initially from the system tables.

For the variables, yes I should be able to extract the content from that table and the linked content. How do we want them included in the export? Do they all belong to a category of "Variables" with the variable name as the keyword? Or do they need to be in a sub category?

Category would be "Variables", sub-categories would be "Aria System Variables", "Aria Status Variables", "MyISAM System Variables", "General System Variables" etc. and then the individual variable keywords.

So we will need a way to organize these in the admin or split https://mariadb.com/kb/en/mariadb/documentation/variables-and-modes/full-list-of-mariadb-options-system-and-status-variables/ up into different sections.

Suggestion from Monty based on how MySQL used to do it. Add tags in the article text to allow portions of an article to be included, in cases where we don't want the entire article to be included.

Help contents have not been updated for nearly three years. One or another way, it needs to be done.
Also, I added 10.0 to the list of 'Fix version/s' – while 5.5 might be more or less okay, since it does not differ that much from MySQL, for 10.0 it's certainly a problem.

This is stalled at the moment as there's been no progress on generating the contents from the Knowledge Base. I have given Monty an updated version of the fill_help_tables.sql script that I made in December, which keeps the same contents, but at least links to the MariaDB KB, but this hasn't been uploaded yet.

Bryan, has there been any progress on the changes above?

This was updated with this commit: https://github.com/MariaDB/server/commit/d983565

Still mostly generated from the old MySQL content, but at least it points to the updated documentation on the MariaDB KB now. I have access to the KB db now, and will look at generating the content automatically at some point.

As per Federico's suggestion on the mailing list, HELP should generate a warning until this is fixed.

Thank you, all of you who were involved in fixing this!