Proposal for the improvement of the reference documentation

Hello there,

Over the last few days, I have been quietly working on a new documentation generator for G’MIC commands. I’m starting to get something usable, so I’m sharing it:

https://gmic.eu/reference/categories

I’d be interested in your feedback. Do you think this is something that is going in the right direction?
In the long run, I’d like to elaborate on the descriptions a little more. Compared to the previous version of the reference documentation, I have also included the commands documented in the gmic-community repository.

Please, let me know what you think about it!

1 Like

Bonjour,

It’s a good idea to group them by categories and by author.

These commands should also be documented in ‘The Handbook’ online and pdf.

The list of commands is too long and it is necessary to delete the commands which give very similar results and especially the commands which do not work.

The authors of these G’MIC commands must try them properly and avoid reinventing the wheel.

:o)

Very nice! Gives a relatively good overview.

I am surprised about the gmic-community things. Still consider your “system” routines as a bit more important, hence I would recommend to put the user functions from gmic-community in one separate category, possibly still grouped by user and by already given subtitles.

Formally I would prefer the boxes more regular and not centered.

If the documentation generator could be used by the gmic-community users directly, I think documentation parts could be easier improved, corrected and extended.

Been waiting for a change. My ideal doc interface would be to have a search box with suggestions, and then another more traditional link or list view. E.g. when we press the / key in GIMP. It would search not only the name but also the description. Right now we are given #@cli comments only. Maybe a new tag for description or keywords would help because I sometimes included other details that won’t be relevant for search.

I know I try to be funny most of the time but I am not sure Funny One-Liners is a good category in name and purpose.

I agree. I really want a way to have more influence over the documentation. I mean play with it to see what works and doesn’t. It will be a way to move this forward because I have lots of ideas. Giving us some mobility would help us think through this problem together and improve the docs even more in the future.

Sorry, but this is not something I know how to do. Apart from generating static HTML pages, everything else is beyond my knowledge in web programming.

When everything will be ‘ready’, I can write a short tutorial about how you can generate a web page for your command.

To be perfectly clear: I believe the whole website of G’MIC should be revamped :slight_smile:
Maybe it should be done before starting to generate new pages.

@patdavid and co could help. :wink: We have lots of talent here. :+1:

I agree. Have fun!?

1 Like

A search field that helps filter out possibilities, searches and highlights in both function name and function content… and tolerates typographic mistakes thanks to levenshtein distance. Results would be command name + command description first letters.

This is showcased here: https://www.youtube.com/watch?v=iyj-Nyde-G4&feature=youtu.be

Sphinx (the doc generator for gmic-py) does some JS-based indexing and searching without any database instance up and I have seen in the past JS-levenshtein matchers already… For Ctrl+F is OK but it does not search in descriptions and does not tolerate mistakes…

Old blog post on top JS fuzzy search libraries: https://bashooka.com/coding/javascript-fuzzy-search-libraries/
I could find one for you if you miss time

I like these grids. Alongside the old reference it’s pretty nice to have them broken down into categories, and I can find a few things I haven’t seen before…

Here is a small tutorial on how to generate the new (WIP) reference pages, for testing.
This requires several steps. The instructions below should work for any Linux distribution, as well as MSYS2 for Windows users.
The CLI tool gmic of G’MIC is used to generate the pages, so make sure it is already installed and available from your executable PATH.

  1. Clone the git repo of the G’MIC project and activate the develop branch.
$ https://github.com/dtschump/gmic.git
$ cd gmic
$ git checkout develop
  1. Go to the html folder, and create an empty test directory where all the generated files will be put.
$ cd gmic/html
$ mkdir test_ref
$ cd test_ref
  1. Generate all the images for the reference documentation (beware, this takes some time!).
$ mkdir img
$ cd img  # Go to 'gmic/html/test_ref/img/'
$ gmic up parse_cli images
  1. Generate the HTML files of the documentation (one file per command).
$ cd ..   # Go back to 'gmic/html/test_ref/'
$ gmic parse_cli html
  1. Open your web browser, and go to URL : file://PATH_TO_GMIC/gmic/html/test_ref/categories.html.

You should be able then to browse the doc.
Note that this is still work in progress. Any feedback welcome. I’ve recently learnt how CSS works, and I’ve not used it a lot in the doc. This is gonna be improved in the future.

1 Like

Works quite well, thank you.

Just a minor remark: for long custom function names word wrap and two liner boxes would be good for the overview.

I’ve made good progress on the doc generation today. I uploaded an updated version.

https://gmic.eu/reference2

Nice progress, with word-wrap etc.

Still there is in my build of the links one ‘html’ to much:

file:///Users/karo/sw/gmic/html/test_ref/animate3d.html.html#top

You’ll have to update the stdlib in one hour or so to fix this :slight_smile:

To make it fun, let the user choose from a set of input images or integrate a simpler version of G’MIC online.

My priorities right now:

  • Finalize the structure of the HTML reference documentation, and put it on the website to replace the older one.
  • Do the same for the .pdf version (which means I have to write a parse_cli_latex command, quite a pain).
  • At this point, I’ll be able to remove the document_gmic command that won’t be used anymore.
  • Write a post about the difference between stylize and fx_stylize for @lesolorzanov.
  • Then I’ll be able to start writing more detailed stuffs about the commands in the reference documentation.

Note that these are priorities concerning G’MIC, but I have of course other things that are inserted into this list, about my research work, the management of my research team, things to do for home and kids (xmas presents…). Sometimes I feel G’MIC is eating too much of my time.

1 Like

Sometimes? :joy_cat:
I can be lost in the moment as well.

Just had a look into the new documentation: really good, much better for me to find things!

Just one minor correction

Instead of “var$i” I would write “vari” or “var{i}”. One could read “var$i” is named “var[parameter i string]”.

About the doc: I’ve been working on it intensively the last days, and I think the improvements are really great. G’MIC has now its own light Markdown syntax that is used in the reference documentation and command description. It’s not as complete as the reference markdown, but at least it is entirely managed by G’MIC itself, so I don’t need external dependencies to generate the G’MIC documentation.
Hopefully, I’ll share more news when it’s ready.

1 Like