Opened 9 years ago
Closed 4 years ago
#8 closed task (fixed)
User Manual rework
|Reported by:||Adrien Destugues||Owned by:||Thomas Bernard|
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 , 5 years ago
|Milestone:||2.5 → 2.6|
comment:2 by , 5 years ago
|Status:||new → assigned|
comment:3 by , 5 years ago
comment:4 by , 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 , 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
comment:6 by , 5 years ago
Generated doc now available at http://pulkomandy.tk/GrafX2/
Updated every night at the same time as the doxygen.
comment:7 by , 4 years ago
|Milestone:||2.6 → 2.7|
Move open tickets to 2.7 milestone
comment:8 by , 4 years ago
also available here : http://grafx2.gitlab.io/grafX2/
I added the icons : https://gitlab.com/GrafX2/grafX2/merge_requests/193
comment:9 by , 4 years ago
|Status:||assigned → closed|
Looks good enough to close this now. Thanks :)