Greetings: First of all, thank you to everyone who responded. I really only expected a few replies, but it seems that many of you here are multi-talented, and I thank you all for your messages and offers of assistance. I received so many replies that I thought it might be better to respond to the list (rather than individually), and I want to expand the topic anyway. After some consideration I've decided to bring the original topic to the list. I'm preparing some documentation for a project, and I need to make some "instructive" screenshots, what Steve D tells me are called callouts. Brett McCoy suggested I use layers in the GIMP, which seems pretty do-able to me, but someone else suggested that I might be better off using something like xfig. I want to do a simple thing (well, to me it's simple, but that's because I don't know how to do it), I want to place a screenshot against a larger white background, which would server as an area for descriptive text. Arrows would point from the text to the item described, and ideally those arrows would be placed at any needed angle. Considering how often I see this type of picture I'd assumed it would be simple in the GIMP: would I in fact be better accomodated by some other graphics app ? The topic has got a bit bigger in my mind now, so I thought I'd ask this question on the open list: Do users have a preference for documentation format ? I admit that while I like HTML it does look rather clunky next to a polished PDF file. Trouble is, I don't know how to format for PDF. So, what format would you prefer ? I've noted this thread as OT, hopefully no-one will be bored to tears by it... :) Best regards, dp

--- Dave Phillips <dlphilp(a)bright.net> wrote: I do everything with docbook-xml and am able to generate .txt, html, pdf, etc from the xml file. It's a solid strategy but I don't know how you should go about doing something like that. It's a no brainer to create templates for things like QuikToots. The templates define the formating tags, custom icons for admonitions, etc. With a CVS server it would be a breeze to manage document versioning. I imagine the distributions have gotten friendlier about building the translation tools and enviroment but don't know if that's true. A cron job fires periodically and updates the documents. The worst thing that can happen to a writer is they spend time administrating publishing environments when they should be writing. Maybe someone could setup a CVS server and the publishing tools and then you could pull the updates to your server. If the above becomes feasible, I'd be happy to markup my Loudness document with all the appropriate tags and then strip it down to something that can be used as a template of sorts for QuikToots. ron __________________________________ Do you Yahoo!? The all-new My Yahoo! - Get yours free! http://my.yahoo.com

lots of ways to do this. Heres one totally biased opinion. For speed, i wont justify anything - ask if neccessary. so wheres this stuff gonna end up? If the web is the primary medium, then imo you must use html. Pdf is a print format. There is no real reason for a pdf to look better than an html document. Ok, there is the issue of fonts, pdf giving the oportunity for the author to embed his choice of font. Html alllows the user to specify the font to his taste, but unfortunately lots of people dont. If your html docs look bad, i highly suspect you dont have any good fonts on your system. There arnt that many good free fonts so you have to augment your installation with some others. Lots of web sites are designed for MSVerdana for example, so just installing that font will help a lot. an html wiz could do this totally in html and css but its not easy. A big png wrapped in html is probably an acceptable compromise. The png shouldnt be too big if it contains large areas of white. bitmap or vector editor? This job is half way between the two so you could go either way. Personally i would use an svg vector editor such as Sodipodi or Inkscape. I think this is probaly more flexible than using Gimp, eg if you want to make subtle changes. Currently displaying svg on the web is problematic, but hopefully it wont be within the next couple of years. In the meantime, export the svg to a png. should you need it, you can also export svg to pdf via the printing system, using the pdf filter, but personally i find this doesnt always work too well. Scripting? If you have a lot of these to do, you can script either gimp or svg for example. Its a non-trivial task, but it would be nice for example to automate the arrows, which is tedious to do manually. good luck! -- Tim Orford

I guess I'm one of those documentation purists :) I would use LaTeX for anything that has some structure to it, such as chapters, sections, appendices, figures, etc. There is an initial learning curve, but it pays off very quickly because you can entirely focus on content once you've got the hang of it, and leave all the formatting decisions to LaTeX. LaTeX will also count chapters and figures and such for you, prepare a table of contents, lists of figures and tables, etc. It'll manage your bibliography as well. The finished product will have a professionally typeset look, and you can export it to ps, pdf, html, etc. Another advantage is that it's easy to change formats. For instance, if you're writing a book but don't have a publisher yet, then you can typeset your book in a generic book style. When you find a publisher, chances are that they've got their own LaTeX style for books that'll yield their specific look and feel. Ideally, you could then switch from the generic style to the publisher's style just by changing the very first line of your document. If you feel that LaTeX may be the right tool for you, I'd be more than happy to tell you more about it. Also, if you're reluctant to tackle LaTeX in its pure form (which may look rather daunting), you can use a LaTeX front end called LyX that sort of resembles familiar word processors. As for pictures, I agree that xfig is a decent tool for the job you described. If you end up choosing LaTeX and xfig, then one added benefit is that you can tell LaTeX to typeset the annotations of your xfig illustrations in a font that'll fit the rest of the document. I've automated much of the interplay between LaTeX and xfig using Unix tools like make and such. Again, if you feel that this is the way to go, I can tell you more. Hope this helps, Peter

Last Friday 26 November 2004 14:58, anahata was like: My 10 year old son rates OOo Draw as the most intuitive art package - he uses it to create designs for trading cards, which is a similar sort of discipline. It rocks for quickly knocking up a design or two. It's a small step for anyone used to Linux Audio mountain climbing adventures. ;-) cheers tim hall http://glastonburymusic.org.uk

Dave Phillips wrote: Dave, Sounds like Gimp with screen cap and cropping along with OpenOffice for text, arrows and formatting all exported as PDF would be an effective, efficient, and easy to master solution. I've done this with a large amount of computer application instructional materials and though I have shed some tears they've not been due to boredom... Frank