Re: Improving the documentation aesthetics

Tom von Schwerdtner wrote:

>Hello all,
>
> Initial run over the style.css is here:
>
>http://people.etria.com/~tvon/AbiHelp/
>
> It has a few issues and is generally incomplete, but you get the idea.
>
>
I really like this, especially with the more-standard swoosh A on the
below link. :)

> And a quick run at improving the general doc-reading experience is
>here (basically adding helper images):
>
>http://people.etria.com/~tvon/abihelp-sample/dialogfind.html
>
>
>
These look nice, the only thing I'm wondering is if there are perhaps a
few too many redundant images (that say the same as their header).
Perhaps a numbered dialog would be better and not give an impression of
"talking down" as much?

> ..which leads to a problem... How should I be adding images to the
>documentation? It seems you have to make an educated guess to size
>the image so it will come out right in the generated html which is
>tedious and time consuming. Is there a better way I'm missing?
>
>
>
No idea, just looked like it was eyeballed in the ABW, but there could
be great magic behind it.

> Someone on IRC (I forget who, sorry) sugested that it would be nice
>if we could have images for each OS stored in the package and
>selected/inserted into the docs when they are generated. I have no
>clue how this would be accomplished without manually editing the .abw
>files. Anyone have an idea?
>
>
To be honest, I took a brief look at the Docs build stuff, and it
doesn't look like it would be terribly difficult. It appears that the
Abi HTML output dumps embedded images into a "index.html_files" or
similar folder, numbered sequentially. If alternate folders could be
created and committed to CVS outside of AbiWord, that, if present, the
script would copy in over the "default" embedded ones, this could be
implemented incrementally. It looks like the Perl script in the
abiword-docs module does most of the heavy lifting, however, I know
neither Perl nor shell scripting well enough to do this on my own.
However, it does appear that it would not be too hard, possibly the
hardest part knowing the target platform (just all the standard creation
of html, check for alternate platform folder, copy in alternate platform
images).

I do know that patches are accepted, and if I get a chance, I will learn
enough Perl to get this done, possibly by 2.4. Filing a bug probably
wouldn't hurt, as an RFE, as I know I'd like to see this, too.

>Regards,
>Tom
>
>
>

-- 
Ryan Pavlik
--
"Forget injuries, never forget kindnesses."  --Confucius