Hi Daniel and All, For off thanks for joining this list, and your interest in documentation, we need it very well actually.
I don't know how you guys imagined writing documentation, but if it's meant to be committed to Harbour SVN (which would definitely a good thing, and this is how other "serious" project do), the format should be simple, text file based and electronically processable using open source tools. We already have NanForum file format which suits these parameters, plus April has written us a pretty good processor tool, called hbdoc2. All in Harbour .prg. We also have a storage medium: SVN. This allows multiple users to add/edit documentation, without adding any new tools into the mix. We also have an amount of already written documentation in this format, in SVN. Many of us liked Vailton's proposal posted yesterday to this list very much, which is also based on current tools and formats. I think we should follow that direction. Of course, I'm happy if anyone is _writing_ any documentation using any tool, but if the goal is to be part of Harbour SVN in the future, IMO you should check these existing tools and try to match the basic requirements. Once we have the doc in such text format, it can be relatively easily processed into _any_ other source format, be it DocBook, LATEX, Robodoc, and any kind of final format, like HTML, .rtf, .pdf. As for the storage type, it can be .dbf, sqlite or any indexing engine, too, but that's really the presentation part, not creation. So, I'd suggest to grasp current format. [ Unfortunately the link didn't open here, and I have no information on Sphinx, the closest I've found is a full text search engine. ] Brgds, Viktor On 2010 Feb 18, at 03:24, Daniel Gonçalves wrote: > Ok! I'll use the "golden rule" of open-source world with my proposal: > "release early, release often"! > > I've published an example of what we can achieve with Sphinx. But > first, keep in mind that it's a less than 3 hour work without a good > view of "what next". I talk this afternoon with Vailton about > Harbour's documentation and our options, how can we do this and wich > tools are widely (wich means accessible and documented) available. We > figured out that we have very similar projects: him with his cool > wxweb project and me with the apix (api extractor). Both doing almost > the same thing. My project goals is to extract documentation blocks > from the source and produce HTML output or reST documents that can be > embedded in a wider Sphinx based documention project. The problem with > api inside sources is just about the developer "culture" and the > internationalization is almost impossible (imagine a single source > with, say, 20 functions, and four languages documenting each > function!). > > I proposed the use of Sphinx. I started a documentation project and > the results can be found here > [http://www.base4.com.br/~daniel/hb/index.html]. The sources are also > available. > > Regards! > > 2010/2/17 Viktor Szakáts <harbour...@syenar.hu>: >>> 2010/2/17 Viktor Szakáts <harbour...@syenar.hu>: >>>> Such topic really belongs here, not the users' list. >>> we can't impose limitation in argument on userlist >>> freedom is magic word, or nobody stay in user list >>>> I only had a short peek into it, but IMO it's not best >>>> direction to start evaluating (for the 10th time) all >>>> the available documentation tools. We've been trough >>>> it 1 year ago, 2 years ago... >>>> >>>> IOW we're over that, NF (NanForum) format is just perfect >>>> and the next logical step is to actually write docs :) >>> >>> we need a path for made a good collaborative work >>> without this path nobody can start in help harbour in having a good >>> documentation >>> so if same body with a good experienced give a way we must evaluate and >>> choice if follow it. >> >> No. Until nobody writes documentation just talk >> about it, there won't be documentation. >> >> It's like if we were discussing what editor or >> coding style we should use since 1999 up until >> today. Imagine how many lines of code would be >> written to date. >> >> Anyway, anyone can write any documentation BTW, >> but I thought it makes sense to flow existing >> information instead of reinventing the wheel >> again and again. Maybe freedom doesn't allow that, >> and you're right. >> >> Brgds, >> Viktor >> >> _______________________________________________ >> Harbour mailing list (attachment size limit: 40KB) >> Harbour@harbour-project.org >> http://lists.harbour-project.org/mailman/listinfo/harbour >> >> > > > > -- > Daniel Gonçalves > Base4 Sistemas Ltda. > [www.base4.com.br] > [twitter.com/spanazzi] > _______________________________________________ > Harbour mailing list (attachment size limit: 40KB) > Harbour@harbour-project.org > http://lists.harbour-project.org/mailman/listinfo/harbour _______________________________________________ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
