Opened 10 years ago

Closed 5 years ago

#8 closed task (fixed)

User Manual rework

Reported by: Adrien Destugues Owned by: Thomas Bernard
Priority: major Milestone: 2.7
Component: GrafX2 Version:
Keywords: Cc:


The user manual is built from C sourcecode with hand-layouted helpscreens. This should be improved:

  • Add a way to search the help by keyword,
  • Export the user manual to text or html to allow reading with a more suitable program and font (our inline help is nice, but with a tiny font it's not very readable).

Change History (9)

comment:1 by PulkoMandy, 6 years ago

Milestone: 2.52.6

comment:2 by PulkoMandy, 6 years ago

Owner: changed from Adrien Destugues to PulkoMandy
Status: newassigned

comment:3 by Thomas Bernard, 6 years ago

Owner: changed from PulkoMandy to Thomas Bernard

comment:4 by yrizoud@…, 6 years ago

I'm not sure that we can expect to have a good html documentation 100% produced from inline context help. It will both require putting lots of data in the C file that only helps html (paragraphs, PREformatted tag, margin, align-right, hierarchical bullet points, embedded images), and may cause the content to be less optimized for the inline viewer (lacking images).

Basically, inline help in Grafx2 should be considered like verbose Tooltip. Coders should easily be able to keep it up-to-date with their changes.

I see two possible choices for re-using the helpfile outside the actual program:
1) As manually tuned Html / wiki, what we had in the old googlecode site. I like how we could have the index / table of contents include the button's image, so at a glance the user could locate a tool / effect. This page is at (images currently broken), and the various sub-pages are at

2) Direct, pre-formatted, 45-character-wide, ASCII transcript. This is guaranteed to be WYSIWYG, and can be stylized (I mean, nice demoscene font instead of default black Verdana on white text). The small width lends itself well to having it side-to-side with screenshot of the relevant screen. You could have "fake" Grafx2 screens on the left (click on buttons to open windows), and the right side shows the current screen's helpfile. This kind of presentation can be very nice if we use animated GIFS capturing the usage of a drawing tool or effect.

I wish it was possible to include this help output as part of the (automated) build process, so that we get the result in the git tree. Otherwise, anyone who needs to update manually-tuned documentation needs to run several versions of the program before doing a file-compare of their outputs.
In any case, the build process should always work for people who have the sources outside of git, so it cant' be a default "make" target.

comment:5 by Thomas Bernard, 6 years ago

I think the result is not too bad.
See doc/html/grafx2_24.html or doc/html/grafx2_41.html for how the inline documentation "ASCII art" displays in HTML.

I think @PulkoMandy can add 'make htmldoc' to the automated build process and make the doc available online on this website

comment:6 by PulkoMandy, 6 years ago

Generated doc now available at
Updated every night at the same time as the doxygen.

comment:7 by PulkoMandy, 5 years ago

Milestone: 2.62.7

Move open tickets to 2.7 milestone

comment:9 by PulkoMandy, 5 years ago

Resolution: fixed
Status: assignedclosed

Looks good enough to close this now. Thanks :)

Note: See TracTickets for help on using tickets.