Opened 6 years ago

Closed 14 months 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:

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 Changed 2 years ago by PulkoMandy

Milestone: 2.52.6

comment:2 Changed 2 years ago by PulkoMandy

Owner: changed from Adrien Destugues to PulkoMandy
Status: newassigned

comment:3 Changed 2 years ago by Thomas Bernard

Owner: changed from PulkoMandy to Thomas Bernard

comment:4 Changed 2 years ago by yrizoud@…

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 Changed 23 months ago by Thomas Bernard

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 Changed 20 months ago by PulkoMandy

Generated doc now available at http://pulkomandy.tk/GrafX2/
Updated every night at the same time as the doxygen.

comment:7 Changed 18 months ago by PulkoMandy

Milestone: 2.62.7

Move open tickets to 2.7 milestone

comment:9 Changed 14 months ago by PulkoMandy

Resolution: fixed
Status: assignedclosed

Looks good enough to close this now. Thanks :)

Note: See TracTickets for help on using tickets.