#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:

Description

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, 5 years ago

Milestone:	2.5 → 2.6

comment:2 by PulkoMandy, 5 years ago

Owner:	changed from Adrien Destugues to PulkoMandy
Status:	new → assigned

comment:3 by Thomas Bernard, 5 years ago

Owner:	changed from PulkoMandy to Thomas Bernard

see https://gitlab.com/GrafX2/grafX2/merge_requests/90

comment:4 by yrizoud@…, 5 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 https://code.google.com/archive/p/grafx2/wikis/ManualSidebar.wiki (images currently broken), and the various sub-pages are at https://code.google.com/archive/p/grafx2/wikis.

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, 5 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