Menu
▾
▴
firebird-docs
|
From: Paul V. <pa...@vi...> - 2003-09-10 22:37:09
|
Hello all, This message is intended for everybody who is planning or considering to help with the Firebird docs. As said earlier, practically everything will have to be written from scratch. Helen Borrie, who has lots of experience with doc writing, advised us to develop a how-to on writing Firebird docs. I think this is a good idea, but I would like to know if there's anybody out there who's really going to write something in the next couple of months, and thinks this might be helpful. Or who would be willing to contribute to such a how-to, even if only by discussing here what should go in it. Or... is there anybody out there now saying "Yes, I'd like to help writing docs and I have the time too, but I need a place to start, I need guidelines or else I don't know how or where to begin" ? You see, no matter how good the idea is, it _is_ another document to write. Is it worth investing time in a howto at this stage if noone is going to write "real" docs anyway? Or if the few people who may start soon don't really feel they need one? Myself I wanted to start with the API documenation a month ago, but due to a lot of extra work I just didn't find the time. Hopefully things will be better soon, but I'll never have a _lot_ of time. That's why I want to spend my doc writing hours in the most effective way. Greetings, and good wheather upon you all, Paul Vinkenoog |
|
From: Paul V. <pa...@vi...> - 2003-09-13 14:36:55
|
Hello, > This message is intended for everybody who is planning or > considering to help with the Firebird docs. > > As said earlier, practically everything will have to be written from > scratch. Helen Borrie, who has lots of experience with doc writing, > advised us to develop a how-to on writing Firebird docs. I've received some reactions off-list, and they made clear that there really are people who want to write docs, and that a how-to and/or guidelines would be greatly appreciated. So... let's make a how-to. What should go in it? My first, rough idea looks something like this: 1. A how-to on getting the manual module to work, with: - getting and installing Java 2 - getting and installing CVS - checking out the Firebird manual module - building the docs that are already there - what to do if things don't work This would be for people who are at least considering to write docs. If we make such a how-to and we think it's good, we should have it placed in the Files section at SourceFource, and ask IBPhoenix to place a link (or even place the entire how-to as a webpage). Otherwise, you would first have to install Java 2 and CVS, check out the manual module and build the docs in order to read how to accomplish the things you have just done :-) A lot of the above information is already out there somewhere - I can't find it on www.ibphoenix.com right now but maybe I didn't look in the right place - but it's scattered and outdated here and there. David Jencks wrote quite a bit of useful stuff; it's in the manual module. 2. A how-to for those who really _are_ going to write docs, with: - how to pick a subject and where to discuss/announce it - why we really want you to write DocBook XML - general as well as fbdocs-specific DocBook instructions + tips - how to structure your document - style guidelines/tips - how and where to ask for commit rights - dos and don'ts if you have received commit rights Of course the two documents should refer to each other. If they turn out really small, they might even be combined into one. Again, these are just rough outlines as they come up in my head right now, I'm not at all saying that it must be like this! Looking forward to your comments, Paul Vinkenoog |
|
From: Tilo M. <tm...@al...> - 2003-09-13 16:16:52
|
Hi Paul, "Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag news:Pin...@so...... > 1. A how-to on getting the manual module to work, with: > - getting and installing Java 2 Here I suggest a simple link to the SUN download page. Additionally we can add the stuff which is really needed to get our manual module compiled (CLASSPATH,...). > - getting and installing CVS Why not use this description? http://sourceforge.net/docman/display_doc.php?docid=766&group_id=1 > - checking out the Firebird manual module > - building the docs that are already there > - what to do if things don't work Agreed. > This would be for people who are at least considering to write > docs. If we make such a how-to and we think it's good, we should > have it placed in the Files section at SourceFource, and ask > IBPhoenix to place a link (or even place the entire how-to as a > webpage). Otherwise, you would first have to install Java 2 and > CVS, check out the manual module and build the docs in order to > read how to accomplish the things you have just done :-) I think our goal should be a nightly build of the html docs which then can be made available online. > 2. A how-to for those who really _are_ going to write docs, with: > - how to pick a subject and where to discuss/announce it > - why we really want you to write DocBook XML > - general as well as fbdocs-specific DocBook instructions + tips > - how to structure your document > - style guidelines/tips > - how and where to ask for commit rights > - dos and don'ts if you have received commit rights Sounds good. We can use preface.xml where most of the required topics is already available. > Looking forward to your comments, > Paul Vinkenoog -- Regards, Tilo Muetze -- Marathon - The SQL Tool for Firebird & InterBase http://gmarathon.sourceforge.net |
|
From: Paul V. <pa...@vi...> - 2003-09-13 23:26:14
|
Hi Tilo (last one for today), >> 1. A how-to on getting the manual module to work, with: >> - getting and installing Java 2 > > Here I suggest a simple link to the SUN download page. Yes, that's what I had in mind: no lengthy explanations, just tell them what they need (at least JRE; JDK if they want to) and where to get it. >> - getting and installing CVS > > Why not use this description? > http://sourceforge.net/docman/display_doc.php?docid=766&group_id=1 It's very lengthy, and specific to WinCVS. I'd prefer to give pointers to command line CVS, WinCVS and TortoiseCVS. WinCVS is fine, but TortoiseCVS is so easy and intuitive that it's almost a laugh! It also has SSH built in, unlike WinCVS. After that, a short explanation of how to ckeckout the manual module, with examples for all three programs. Same for update -dP. With read-only access, that's all they'll ever need. > I think our goal should be a nightly build of the html docs which > then can be made available online. That would be nice. But is this automatable on SF? Greetings, Paul Vinkenoog |
|
From: Tilo M. <tm...@al...> - 2003-09-18 22:37:09
|
Hi Paul, "Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag news:Pin...@so...... > > Why not use this description? > > http://sourceforge.net/docman/display_doc.php?docid=766&group_id=1 > > It's very lengthy, and specific to WinCVS. I'd prefer to give pointers > to command line CVS, WinCVS and TortoiseCVS. WinCVS is fine, but > TortoiseCVS is so easy and intuitive that it's almost a laugh! It > also has SSH built in, unlike WinCVS. > > After that, a short explanation of how to ckeckout the manual module, > with examples for all three programs. Same for update -dP. With > read-only access, that's all they'll ever need. When we do it we need to make sure that this documentation is always up-to-date. IMHO, our task should be writing Firebird docs and not redundant CVS docs. I recommend using the SF WinCVS doc to give the user a introduction to CVS and SSH setup at SF. Then we can simply suggest TortoiseCVS and command line CVS. We should also point the users to a good CVS documentation like http://cvsbook.red-bean.com/cvsbook.html > > I think our goal should be a nightly build of the html docs which > > then can be made available online. > > That would be nice. But is this automatable on SF? What I do for Marathon is to checkout the fresh sourcecode, compile and use scp to put the binaries to the Marathon webspace. Of course this does not work automatically due to my limited internet access. I can add an appropriate build target when my time permits (in Oct.). > Greetings, > Paul Vinkenoog -- Regards, Tilo Muetze -- Marathon - The SQL Tool for Firebird & InterBase http://gmarathon.sourceforge.net |
|
From: Mauricio L. <ml...@ct...> - 2003-10-27 01:23:11
|
Paul, Just to get a better understanding... Why *do* you want the help to be a docbook xml? Please, I don't have any specific objections, but all the steps involved in the discussion list seem to make for a lot of trouble for anyone participating in the effort. Please, bear in mind that I'm not criticizing, and that I have no other suggestion at the moment, but I would like to understand the "whys" in order to decide if I should/could think of someway to contribute. > - why we really want you to write DocBook XML > - general as well as fbdocs-specific DocBook instructions + tips Regards, Mauricio Longo |
|
From: Paul V. <pa...@vi...> - 2003-10-28 13:20:49
|
Hi Mauricio, > Just to get a better understanding... Why *do* you want the help to > be a docbook xml? Please, I don't have any specific objections, but > all the steps involved in the discussion list seem to make for a lot > of trouble for anyone participating in the effort. Please, bear in > mind that I'm not criticizing, and that I have no other suggestion > at the moment, but I would like to understand the "whys" in order to > decide if I should/could think of someway to contribute. I've also received this mail privately and replied (as you know of course). Now I see that you posted it to the list too, but it took a couple of days to show up - I think SF has a random delay function built in somewhere in the mailing list chain :-) Anyway, since the question is now on the list, I'll post my answer here too, because other people may have the same question. It's been answered before, but the archives are not always accessible - the interface at SF is a bit awkward, often slow and I think also incomplete; and the NNTP mirror at news.atkin.com has problems regularly (right now it's down). So here goes: > Just to get a better understanding... Why *do* you want the help to > be a docbook xml? Because with DocBook XML, you mark up the _structure_ of a text and the _meaning_ of its elements: you tag things as chapters, sections, subsections, titles, warnings, code snippets, filenames, tips, user commands, etc. etc... There is no "pollution" by presentational markup like in HTML, RTF, Word and other formats. This results in a very clean and structured source text which is easy to maintain, totally platform-independent *and* presentation- independent, From this DocBook XML source, we can then (automatically) build HTML, PDF and other output for the readers. Stylesheets (which we can change if we want to) control how the structural markup is translated to a certain presentation. > Please, I don't have any specific objections, but all the steps > involved in the discussion list seem to make for a lot of trouble > for anyone participating in the effort. I'm afraid you are right :-( It takes time to get familiar with DocBook XML. Ten months ago I'd never heard of it - I learned using it because I wanted to help produce Firebird documentation. But now that I know it, I find it even easier to write then HTML or Word or whatever, precisely because I never have to worry about the layout while I'm writing! If I write a text in Word, I have to think about if I want section titles bold or not - or perhaps in a nice color? - and then I have to remember my decision so I don't do it another way ten pages further down. And how do I make up a code snippet? And a command line? And a warning? And... and... aaaargh! But even if I *do* make some great rules for all these elements, and I *do* apply them consequently throughout the text, the resulting document will still suffer from these drawbacks: - The information itself as to whether something is a code snippet, a warning, or a filename, is not included in the document - because I've already translated that info to makeup: font types, colors etc. - I only have a Word text now. How to convert to PDF and HTML? Yes, I know: the latest Word versions do that, but you can't really control _how_ they do it. If I write DocBook XML on the other hand, I rarely have to think about which tags to use, because In DocBook you tag a command as <command>, a filename as <filename>, a code snippet as <programlisting>, etc... Easy! Also, if everybody produces DocBook XML, we can have one common output style (defined by the stylesheets). If we'd all produce HTML it would be very difficult (and very frustrating for the docwriters) to have a common style. But - having said all that - if someone wants to help and he REALLY has a big problem with DocBook XML, he can write in another format too. But I hope everybody will at least give DocBook a good try before they decide not to use it. I hope I can finish the first - draft - Howto this week; it's about how to download the manual module and build the docs. A second Howto (hopefully within three weeks) will be on how to write docs in DocBook XML format. Greetings! Paul Vinkenoog - no docs today, my mind has gone away - |
|
From: Frederic G. M. <fg...@os...> - 2004-06-03 23:30:19
|
As I've been working on the Gbak format and Helen and Ann suggested so, I'll probably put up a small document on this subject. How should I do it ? I normally work in OO or Word with custom stylesheets for my usual artifacts, which seem similar to what you describe for Docbook. Can I use these and just paste the elements in a docbook skeleton somewhere ? (where ?). "Paul Vinkenoog" <pa...@vi...> a écrit dans le message de news:Pin...@s4...... > Hi Mauricio, [...] > Because with DocBook XML, you mark up the _structure_ of a text and > the _meaning_ of its elements: you tag things as chapters, sections, > subsections, titles, warnings, code snippets, filenames, tips, user > commands, etc. etc... There is no "pollution" by presentational > markup like in HTML, RTF, Word and other formats. > > This results in a very clean and structured source text which is easy > to maintain, totally platform-independent *and* presentation- > independent, > > From this DocBook XML source, we can then (automatically) build HTML, > PDF and other output for the readers. Stylesheets (which we can change > if we want to) control how the structural markup is translated to a > certain presentation. > > > Please, I don't have any specific objections, but all the steps > > involved in the discussion list seem to make for a lot of trouble > > for anyone participating in the effort. > > I'm afraid you are right :-( > > It takes time to get familiar with DocBook XML. Ten months ago I'd > never heard of it - I learned using it because I wanted to help > produce Firebird documentation. But now that I know it, I find it even > easier to write then HTML or Word or whatever, precisely because I > never have to worry about the layout while I'm writing! > > If I write a text in Word, I have to think about if I want section > titles bold or not - or perhaps in a nice color? - and then I have to > remember my decision so I don't do it another way ten pages further > down. And how do I make up a code snippet? And a command line? And a > warning? And... and... aaaargh! > > But even if I *do* make some great rules for all these elements, and I > *do* apply them consequently throughout the text, the resulting > document will still suffer from these drawbacks: > > - The information itself as to whether something is a code snippet, a > warning, or a filename, is not included in the document - because > I've already translated that info to makeup: font types, colors etc. > > - I only have a Word text now. How to convert to PDF and HTML? Yes, I > know: the latest Word versions do that, but you can't really control > _how_ they do it. > > If I write DocBook XML on the other hand, I rarely have to think about > which tags to use, because In DocBook you tag a command as <command>, > a filename as <filename>, a code snippet as <programlisting>, etc... > Easy! > > Also, if everybody produces DocBook XML, we can have one common output > style (defined by the stylesheets). If we'd all produce HTML it would > be very difficult (and very frustrating for the docwriters) to have a > common style. > > > But - having said all that - if someone wants to help and he REALLY > has a big problem with DocBook XML, he can write in another format > too. But I hope everybody will at least give DocBook a good try before > they decide not to use it. > > > I hope I can finish the first - draft - Howto this week; it's about > how to download the manual module and build the docs. A second Howto > (hopefully within three weeks) will be on how to write docs in DocBook > XML format. > > > Greetings! > Paul Vinkenoog > > - no docs today, my mind has gone away - > > > > ------------------------------------------------------- > This SF.net email is sponsored by: The SF.net Donation Program. > Do you like what SourceForge.net is doing for the Open > Source Community? Make a contribution, and help us add new > features and functionality. Click here: http://sourceforge.net/donate/ > _______________________________________________ > Firebird-docs mailing list > Fir...@li... > https://lists.sourceforge.net/lists/listinfo/firebird-docs > |
|
From: Paul V. <pa...@vi...> - 2004-06-04 00:28:51
|
Hi Fr=E9d=E9ric, > As I've been working on the Gbak format and Helen and Ann suggested > so, I'll probably put up a small document on this subject. > > How should I do it ? I normally work in OO or Word with custom > stylesheets for my usual artifacts, which seem similar to what you > describe for Docbook. Can I use these and just paste the elements > in a docbook skeleton somewhere ? (where ?). Will you write one small doc and nothing more? Then you shouldn't probably bother with DocBook at all. Just write it in plain OO or Word without any fancy formatting stuff, and I'll convert it to DocBook. You can generate DocBook with OO 1.1.1 but I personally find it rather awkward. Carlos seems to be doing OK with it though :-) If you want to take the DocBook-with-OO route, read http://xml.openoffice.org/xmerge/docbook/UserGuide.html =2E..and also get that template they link to. If you think you're going to write more technical docs in the future (not necessarily for Firebird), learning DocBook may be very benificial for you. You can find all you need in the Firebird Docwriting Howto (but this will cost you at least an hour to read and understand): http://www.firebirdsql.org/devel/doc/manual/defaulthtml/docwritehowto.htm= l Greetings, Paul Vinkenoog |
|
From: Helen B. <he...@tp...> - 2004-06-04 01:29:21
|
At 02:27 AM 4/06/2004 +0200, you wrote: >You can generate DocBook with OO 1.1.1 but I personally find it rather >awkward. Carlos seems to be doing OK with it though :-) > >If you want to take the DocBook-with-OO route, read > > http://xml.openoffice.org/xmerge/docbook/UserGuide.html > >...and also get that template they link to. You also need to get the three XSLT files. Actually, this link is better to cover fully what you need to do to activate XML filtering (as I discovered yesterday after several frustrating hours trying to make OO.o 1.1.1 behave as described in the UserGuide.html page). It's incredible that they don't have these two pieces together in one document!! Start here and use method 1: http://xml.openoffice.org/xmerge/docbook/ Once you do this bit, the UserGuide instructions work fine and it's really easy to write an <article> or <chapter> document. >If you think you're going to write more technical docs in the future >(not necessarily for Firebird), learning DocBook may be very >benificial for you. You can find all you need in the Firebird >Docwriting Howto (but this will cost you at least an hour to read >and understand): > > http://www.firebirdsql.org/devel/doc/manual/defaulthtml/docwritehowto.html Confirmed, Paul's Howto is a good coverage of the absolute basics of DocBook. Paul, I'm working on the converter for the Framemaker xml and I really don't think it will be rocket science to write another one for reprocessing the OO docbook output, if it's needed. NB also the usefulness of ConText (www.fixedsys.com/context) for converting your files to UTF-8...unicode...You can, of course, do this with the NT version of Notepad, but Context has a proper highlighter for XML. Helen |
|
From: Frederic G. M. <fg...@os...> - 2004-06-04 10:12:02
|
Yes, thanks, I knew context already: I wrote an ObjectPAL highlighter for it. Really nice editor. "Helen Borrie" <he...@tp...> a écrit dans le message de news:5.2...@ma...... > At 02:27 AM 4/06/2004 +0200, you wrote: > > >You can generate DocBook with OO 1.1.1 but I personally find it rather > >awkward. Carlos seems to be doing OK with it though :-) > > > >If you want to take the DocBook-with-OO route, read > > > > http://xml.openoffice.org/xmerge/docbook/UserGuide.html > > > >...and also get that template they link to. > > You also need to get the three XSLT files. Actually, this link is better > to cover fully what you need to do to activate XML filtering (as I > discovered yesterday after several frustrating hours trying to make OO.o > 1.1.1 behave as described in the UserGuide.html page). It's incredible > that they don't have these two pieces together in one document!! > > Start here and use method 1: > http://xml.openoffice.org/xmerge/docbook/ > > Once you do this bit, the UserGuide instructions work fine and it's really > easy to write an <article> or <chapter> document. > > > >If you think you're going to write more technical docs in the future > >(not necessarily for Firebird), learning DocBook may be very > >benificial for you. You can find all you need in the Firebird > >Docwriting Howto (but this will cost you at least an hour to read > >and understand): > > > > http://www.firebirdsql.org/devel/doc/manual/defaulthtml/docwritehowto.html > > Confirmed, Paul's Howto is a good coverage of the absolute basics of DocBook. > > Paul, I'm working on the converter for the Framemaker xml and I really > don't think it will be rocket science to write another one for reprocessing > the OO docbook output, if it's needed. > > NB also the usefulness of ConText (www.fixedsys.com/context) for converting > your files to UTF-8...unicode...You can, of course, do this with the NT > version of Notepad, but Context has a proper highlighter for XML. > > Helen > > > > > > ------------------------------------------------------- > This SF.Net email is sponsored by the new InstallShield X. > From Windows to Linux, servers to mobile, InstallShield X is the one > installation-authoring solution that does it all. Learn more and > evaluate today! http://www.installshield.com/Dev2Dev/0504 > _______________________________________________ > Firebird-docs mailing list > Fir...@li... > https://lists.sourceforge.net/lists/listinfo/firebird-docs > |
|
From: Paul V. <pa...@vi...> - 2004-06-04 15:31:55
|
Hi Helen, > You also need to get the three XSLT files. Actually, this link is > better to cover fully what you need to do to activate XML filtering > (as I discovered yesterday after several frustrating hours trying to > make OO.o 1.1.1 behave as described in the UserGuide.html page). > It's incredible that they don't have these two pieces together in > one document!! > Start here and use method 1: > http://xml.openoffice.org/xmerge/docbook/ Thanks for finding this out. I did visit that page before but decided not to follow the instructions because it was for Beta/RC versions. Installed that stuff now. Yes, it works, but (for me) it's very counterintuitive. Too used to XXE I guess. Also, if I import and re-export, or if I make a simple new DocBook file, it sometimes exports broken DocBook XML. BTW, to everybody who's going to follow the instructions on that webpage: under "Creating a new DocBook filter" they swapped the import and export stylesheets. The correct choices are: docbooktosoff* for import sofftodocbook* for export > Paul, I'm working on the converter for the Framemaker xml and I > really don't think it will be rocket science to write another one > for reprocessing the OO docbook output, if it's needed. OK, but let's first see if it's needed :-) Carlos is sending me revisions now and then (produced with OO) and they are correct. Greetings, Paul Vinkenoog |
|
From:
<car...@te...> - 2004-06-04 15:59:34
|
Hello: >Carlos is sending me revisions now and then (produced with OO) and >they are correct. > I'm not using OpenOffice on the revisions, i used it only on the first one, for all other i'm using a text editor :) -- Best regards Carlos Guzmán Álvarez Vigo-Spain |
|
From: Philippe M. <mak...@fi...> - 2004-06-04 08:40:28
|
Le 04/06/2004 02:59, Helen Borrie a écrit : > NB also the usefulness of ConText (www.fixedsys.com/context) for > converting your files to UTF-8...unicode...You can, of course, do this > with the NT version of Notepad, but Context has a proper highlighter for > XML. Notice that under Linux, Kate is a good tool for working with xml docbook I also discover that under Windows you can do html help (.chm file). |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X