RE: [Harbour] Re: About Harbour Documentation
rant It hard to object if you already deleted them an hour later. You can say that ALL docs are 8 or 10 years old so why don't just delete it all and be done with it. Some of the ES docs where translation of original EN for standard Clipper/Harbour functions. These should not changed in the past 10 years. I know that the docs were neglected, but sometimes it is better to have some reference to work with (future ES documenter) than to have nothing to start with. (I know they are in the SVN tree but for most users they are now gone). /rant Isn't svn allowing to recover past/deleted/modified versions of all files? If yes, would be easy to undelete them if anyone needs them, Best regards, Marco _ La tua privacy è al sicuro con Internet Explorer 8. Scopri di più http://www.microsoft.com/italy/windows/internet-explorer/features/browse-privately.aspx?tabid=2catid=1___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Marco, Isn't svn allowing to recover past/deleted/modified versions of all files? Of course, and I wrote that: I know they are in the SVN tree Since the docs need to have some major review, it might be best to focus on the English one we have and and new material submitted and only when they updated content, start translation efforts. Chen. ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Chen, rant It hard to object if you already deleted them an hour later. You can say that ALL docs are 8 or 10 years old so why don't just delete it all and be done with it. Some of the ES docs where translation of original EN for standard Clipper/Harbour functions. These should not changed in the past 10 years. I know that the docs were neglected, but sometimes it is better to have some reference to work with (future ES documenter) than to have nothing to start with. (I know they are in the SVN tree but for most users they are now gone). /rant *sigh* above were just some ranting because you already deleted them, I have some pending fix requests I made for them dusting in my mailbox for about a decade. So lets continue. Ok, sorry. I don't think it's very useful for us though. For me it has been giving 'dead' grep hits for years, I've raised this issue in the past a few times, moved it to examples a few years back, so there has quite some chances to save it in the past. Just having something in SVN gathering dust _is_ actually a bad thing and something that slows down other work. If someone wants to restart with it anytime, it can easily be restored from any release of Harbour from the last 5 years. Anyhow I think it's better to focus on English now. Doc function header template can be found in doc/hdr_tpl.txt You're right. I forgot about it. For start anyone want to contribute anything just post it to the list and if no one else volunteer to act as an editor (preferably a native English speaker) I can try to add them into SVN. Later if we will have enough material to work with, we can try adding some indexing along with doc status (like the funclist.txt we had in the old days). Yes. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi! I would suggest introduce an new tag into current NF format: $LASTREVISION$ This would contain the ID of the last time the documentation of a function / procedure was compared with the original source. Thus, we could quickly compare the functions which are outdated and need revision. A simple example would be: /* $DOC$ * $TEMPLATE$ * Function * $NAME$ * ERRORSYS() * $CATEGORY$ * API * $SUBCATEGORY$ * Error * $ONELINER$ * Install default error handler * $SYNTAX$ * ERRORSYS() -- NIL * $ARGUMENTS$ * None. * $RETURNS$ * ERRORSYS() always return NIL. * $DESCRIPTION$ * ERRORSYS() is called upon startup by Harbour and installs the default * error handler. Normally you should not call this function directly, * instead use ERRORBLOCK() to install your own error handler. * $STATUS$ * R * $COMPLIANCE$ * C * $FILES$ * Library is rtl * $SEEALSO$ * ERRORBLOCK(),Error class * $LASTREVISION$ * 11685 2009-07-09 21:22:22Z vszakats * $END$ */ What do you think? Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Viktor! Excellent, I think this will be of great help in this work ... A question only to conclude: the documents what are produced, we can post into SVN or we should send them before for someone to review? Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Vailton, Excellent, I think this will be of great help in this work ... A I'll send an update version soon, still waiting for feedback in some points. (is $VERSION$ okay for everybody? is it okay to use long filenames?) question only to conclude: the documents what are produced, we can post into SVN or we should send them before for someone to review? I think such formal reviewing process is unnecessary at this point. Anyone can review everything on SVN, and issue corrections as needed on SVN, or by sending patches (similar to source code). Since we don't know yet who will actually submit documentation, in the very beginning I think either someone with R/W rights (you, if you take this task :) should commit them on behalf of document writers, or even someone new who volunteers for this task, can get R/W right and do the commits. Later, when we see who exactly needs R/W right to make things run smoother, we can invite those contributors as SVN users. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi! I am available to help when in need... Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi! 2. $SEAALSO# must also follow a certain pattern, say, separated with spaces or comma. Spaces will interfere when we document the commands ... Separated by commas, will certainly be easier. Something like: cSeeAlso: = Strtran (cSeeAlso, ',', ',') cSeeAlso: = Strtran (cSeeAlso, ',', ',') aSeeAlso: = hb_aTokens (cSeeAlso, ',') Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi, $HEADERSFILES$ = Only names separated with , = if it depends on many or only one with primary dependance This is already included in $SYNTAX$ section, I think it's fine as it is: --- * $SYNTAX$ * C Prototype * * #include hbapifs.h * hb_fsChDir( BYTE * pszDirName ) -- ( HB_BOOL ) bResult --- I think $SYTAX$ is enough. Though, I prefer a common C syntax: HB_BOOL hb_fsChDir( BYTE * pszDirName ) $LIB$ = only name without suffix. I was thinking about it, but I'd rather vote to keep Harbour as easy to use as possible, so that users don't have to worry about lib names at all. I find it useful (but not critical). 2. $SEAALSO# must also follow a certain pattern, say, separated with spaces or comma. Definitely. I think it's already defined as comma. If not, we should now define it as comma. Space is not good, as commands may have spaces in them. I guess we have same functions that has the same C and PRG names. It will be impossible to link see also pages. Though, case sensitive link names and upper case names for PRG functions can solve majority of the problem. Regards, Mindaugas ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
$HEADERSFILES$ = Only names separated with , = if it depends on many or only one with primary dependance This is already included in $SYNTAX$ section, I think it's fine as it is: --- * $SYNTAX$ * C Prototype * * #include hbapifs.h * hb_fsChDir( BYTE * pszDirName ) -- ( HB_BOOL ) bResult --- I think $SYTAX$ is enough. Though, I prefer a common C syntax: HB_BOOL hb_fsChDir( BYTE * pszDirName ) Agreed fully. $LIB$ = only name without suffix. I was thinking about it, but I'd rather vote to keep Harbour as easy to use as possible, so that users don't have to worry about lib names at all. I find it useful (but not critical). 2. $SEAALSO# must also follow a certain pattern, say, separated with spaces or comma. Definitely. I think it's already defined as comma. If not, we should now define it as comma. Space is not good, as commands may have spaces in them. I guess we have same functions that has the same C and PRG names. It will be impossible to link see also pages. Though, case sensitive link names and upper case names for PRG functions can solve majority of the problem. Good point. Worst case, parser should make list _all_ occurrences of 'see also' references, so for hb_releaseCPU() f.e., it would list both the .c and .prg level versions, regardless of casing. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
RE: [Harbour] Re: About Harbour Documentation
Hi all, maybe I missed something, and someone has already told it, but I think that the main goal for a documentation is to be always available, so an online documentation must be a plus, a side feature of an offline documentation. There are many files available in the \doc folder but I can't see if there is a file that organize them in any way, such as alfabetical or category order. I'm a user of ng guides that I use almost every day when I don't remember the syntax of a function of the properties of a class. I know it's a very old tool but it does the job very well: to show documentation in a fast and proper way without the need of being on line or to scan \doc folder in search of the right file: I don't know if there is a Linux version too. Another consideration is that many informations that can be useful in advanced documentation can be borrowed from this mailing list: personally I'm registering the messages that I think of important for me. Finally another source is the Changelog. So in addition to documentation team that have been suggested, I think that it's important to have someone that has the time to read Changelog and this mailing list in search of the right answer or the proper implementation of a problem. I know that Changelog is updating fast but theare are informations that are valid documentation itself and the keep valid for a long time. Best regards, Marco _ Parla, scrivi, gioca... Scopri le novità di Messenger http://www.messenger.it/home_novita.aspx___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi, maybe I missed something, and someone has already told it, but I think that the main goal for a documentation is to be always available, so an online documentation must be a plus, a side feature of an offline documentation. There are many files available in the \doc folder but I can't see if there is a file that organize them in any way, such as alfabetical or category order. I'm a user of ng guides that I use almost every day when I don't remember the syntax of a function of the properties of a class. I know it's a very old tool but it does the job very well: to show documentation in a fast and proper way without the need of being on line or to scan \doc folder in search of the right file: I don't know if there is a Linux version too. You missed hbdoc2. Another consideration is that many informations that can be useful in advanced documentation can be borrowed from this mailing list: personally I'm registering the messages that I think of important for me. Finally another source is the Changelog. So in addition to documentation team that have been suggested, I think that it's important to have someone that has the time to read Changelog and this mailing list in search of the right answer or the proper implementation of a problem. I know that Changelog is updating fast but theare are informations that are valid documentation itself and the keep valid for a long time. Yes. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi! When I started the studies on this help format, I found many helpful information about the format NANFORUM in: http://www.kssoftware.com.br/ft_doc.zip And also the code in /harbour/examples/hbdoc2/tmplates.prg Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
2010/2/19 Viktor Szakáts harbour...@syenar.hu: For example, suppose I want to contribute documenting the hbsqlit3 contrib, wich is module I'm very interested. What I'm suposed to do? Create a directory /harbour/doc/en-EN/contrib/hbsqlit3 and write text files in NF format? All contribs are meant to be independent from core, so their docs should be stored in /contrib/name/doc/en-EN/* I searched for this en-EN locale identifier and it does not exists [1], [2] and [3]. It must be changed to en-US. [1] http://tools.ietf.org/html/rfc5646 [2] http://www.i18nguy.com/unicode/language-identifiers.html [3] http://en.wikipedia.org/wiki/Language_code Regards! -- 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
Re: [Harbour] Re: About Harbour Documentation
Hi Daniel, For example, suppose I want to contribute documenting the hbsqlit3 contrib, wich is module I'm very interested. What I'm suposed to do? Create a directory /harbour/doc/en-EN/contrib/hbsqlit3 and write text files in NF format? All contribs are meant to be independent from core, so their docs should be stored in /contrib/name/doc/en-EN/* I searched for this en-EN locale identifier and it does not exists [1], [2] and [3]. It must be changed to en-US. [1] http://tools.ietf.org/html/rfc5646 [2] http://www.i18nguy.com/unicode/language-identifiers.html [3] http://en.wikipedia.org/wiki/Language_code Or rather plain 'en'? Can you confirm, if this is the valid ID for dialect-neutral English language? [ Unless we want to even have separate 'US' and 'GB' English dialect docs, which I believe we don't. ] Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
It's better to use en-US, to better distinguish from others and to avoid mistakes. We should always follow the pattern xx-YY. 2010/2/20 Viktor Szakáts harbour...@syenar.hu: Hi Daniel, For example, suppose I want to contribute documenting the hbsqlit3 contrib, wich is module I'm very interested. What I'm suposed to do? Create a directory /harbour/doc/en-EN/contrib/hbsqlit3 and write text files in NF format? All contribs are meant to be independent from core, so their docs should be stored in /contrib/name/doc/en-EN/* I searched for this en-EN locale identifier and it does not exists [1], [2] and [3]. It must be changed to en-US. [1] http://tools.ietf.org/html/rfc5646 [2] http://www.i18nguy.com/unicode/language-identifiers.html [3] http://en.wikipedia.org/wiki/Language_code Or rather plain 'en'? Can you confirm, if this is the valid ID for dialect-neutral English language? [ Unless we want to even have separate 'US' and 'GB' English dialect docs, which I believe we don't. ] 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
Re: [Harbour] Re: About Harbour Documentation
I think we should use the IETF format, (the W3C model that Viktor mentioned) http://en.wikipedia.org/wiki/IETF_language_tag only two letters, except when we need it. As we lack documentation, at this stage it doesn't make sense to me even to split the pt language into pt-BR (my language) and pt only. We can use the ietf shortest code rule adding the -SUBCODE only when the necessity arrives. You can find the table here: http://www.iana.org/assignments/language-subtag-registry 2010/2/20 Daniel Gonçalves dan...@base4.com.br: Ok Viktor, I suggested the pattern because on other open-source projects I follow and participate, they use the pattern xx-YY, but I will use the rules for Harbour project. I hope you guys understands that I not trying to impose anything. I'm just trying to help using my knowledge and experience from other spheres! 2010/2/20 Viktor Szakáts harbour...@syenar.hu: It's just a pattern, so we all know that always be xx-YY for ALL languages and not xx for that one and for the other, but for another it is xx-YY, i guess! See! To avoid more things to think about! But this pattern is not true to the standard, it can also be xx, xx-YYY, xx-y-zzz, see the RFC. Each have different and meaningful meanings. I've just made an admonition: en-EN does not exists. I know, that's why I started this discussion in the first place :) If we follow a pattern, it will be one less thing to be concerned about. :-) I think we should follow the standard, rather than a limited pattern. If we invent our own pattern, it will not be possible to interchange our language code with tools which adhere to standards. BTW we should only worry about this _once_ for each language we translate our documentation to. So far we have bits in English and Spanish only, so it's not very complicated. Moreover IMO we should first concentrate on English only. 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
Re: [Harbour] Re: About Harbour Documentation
Hi Bacco, I think we should use the IETF format, (the W3C model that Viktor mentioned) http://en.wikipedia.org/wiki/IETF_language_tag only two letters, except when we need it. As we lack documentation, at this stage it doesn't make sense to me even to split the pt language into pt-BR (my language) and pt only. We can use the ietf shortest code rule adding the -SUBCODE only when the necessity arrives. I'm not familiar with Brazil dialect of Portuguese language, but if it's practically different from regular Portuguese, IMO we should use pt-BR as per the standard. We use this code already for Portuguese translation of hbmk2, and I just suspect it was used for good reason. A native speaker is better to make it clear here. All in all, let's use what the standard dictates, and not uniformly xx or uniformly xx-YY. For example, the proper code for Hungarian language is 'hu-HU'. (for generic English it's 'en'). Brgds, Viktor You can find the table here: http://www.iana.org/assignments/language-subtag-registry 2010/2/20 Daniel Gonçalves dan...@base4.com.br: Ok Viktor, I suggested the pattern because on other open-source projects I follow and participate, they use the pattern xx-YY, but I will use the rules for Harbour project. I hope you guys understands that I not trying to impose anything. I'm just trying to help using my knowledge and experience from other spheres! 2010/2/20 Viktor Szakáts harbour...@syenar.hu: It's just a pattern, so we all know that always be xx-YY for ALL languages and not xx for that one and for the other, but for another it is xx-YY, i guess! See! To avoid more things to think about! But this pattern is not true to the standard, it can also be xx, xx-YYY, xx-y-zzz, see the RFC. Each have different and meaningful meanings. I've just made an admonition: en-EN does not exists. I know, that's why I started this discussion in the first place :) If we follow a pattern, it will be one less thing to be concerned about. :-) I think we should follow the standard, rather than a limited pattern. If we invent our own pattern, it will not be possible to interchange our language code with tools which adhere to standards. BTW we should only worry about this _once_ for each language we translate our documentation to. So far we have bits in English and Spanish only, so it's not very complicated. Moreover IMO we should first concentrate on English only. 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 ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
I am a native pt-BR speaker, and I am web developer also, and here we use pt-BR on the web pages. Of course I like the idea to have pt-BR translation (and contribute too). May we agree in the IETF format? Maybe we can add the most wanted language folders to the main doc folder and into dirstruc.txt, to serve as example and eliminate the needs for further discussion about this theme. At least doc/en (just rename back) doc/es doc/pt-BR (maybe some placeholder.txt so it doesnt stay empty) Regards Bacco On Sat, Feb 20, 2010 at 17:01, Viktor Szakáts harbour...@syenar.hu wrote: Hi Bacco, I think we should use the IETF format, (the W3C model that Viktor mentioned) http://en.wikipedia.org/wiki/IETF_language_tag only two letters, except when we need it. As we lack documentation, at this stage it doesn't make sense to me even to split the pt language into pt-BR (my language) and pt only. We can use the ietf shortest code rule adding the -SUBCODE only when the necessity arrives. I'm not familiar with Brazil dialect of Portuguese language, but if it's practically different from regular Portuguese, IMO we should use pt-BR as per the standard. We use this code already for Portuguese translation of hbmk2, and I just suspect it was used for good reason. A native speaker is better to make it clear here. All in all, let's use what the standard dictates, and not uniformly xx or uniformly xx-YY. For example, the proper code for Hungarian language is 'hu-HU'. (for generic English it's 'en'). Brgds, Viktor You can find the table here: http://www.iana.org/assignments/language-subtag-registry 2010/2/20 Daniel Gonçalves dan...@base4.com.br: Ok Viktor, I suggested the pattern because on other open-source projects I follow and participate, they use the pattern xx-YY, but I will use the rules for Harbour project. I hope you guys understands that I not trying to impose anything. I'm just trying to help using my knowledge and experience from other spheres! 2010/2/20 Viktor Szakáts harbour...@syenar.hu: It's just a pattern, so we all know that always be xx-YY for ALL languages and not xx for that one and for the other, but for another it is xx-YY, i guess! See! To avoid more things to think about! But this pattern is not true to the standard, it can also be xx, xx-YYY, xx-y-zzz, see the RFC. Each have different and meaningful meanings. I've just made an admonition: en-EN does not exists. I know, that's why I started this discussion in the first place :) If we follow a pattern, it will be one less thing to be concerned about. :-) I think we should follow the standard, rather than a limited pattern. If we invent our own pattern, it will not be possible to interchange our language code with tools which adhere to standards. BTW we should only worry about this _once_ for each language we translate our documentation to. So far we have bits in English and Spanish only, so it's not very complicated. Moreover IMO we should first concentrate on English only. 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 ___ 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
Re: [Harbour] Re: About Harbour Documentation
On Sat, Feb 20, 2010 at 17:53, Bacco carlosba...@gmail.com wrote: I am a native pt-BR speaker, and I am web developer also, and here we use pt-BR on the web pages. Of course I like the idea to have pt-BR translation (and contribute too). May we agree in the IETF format? Maybe we can add the most wanted language folders to the main doc folder and into dirstruc.txt, to serve as example and eliminate the needs for further discussion about this theme. At least doc/en (just rename back) doc/es doc/pt-BR (maybe some placeholder.txt so it doesnt stay empty) (and eventually others that you are sure that will be needed, of course. These three I know that will be) Regards Bacco On Sat, Feb 20, 2010 at 17:01, Viktor Szakáts harbour...@syenar.hu wrote: Hi Bacco, I think we should use the IETF format, (the W3C model that Viktor mentioned) http://en.wikipedia.org/wiki/IETF_language_tag only two letters, except when we need it. As we lack documentation, at this stage it doesn't make sense to me even to split the pt language into pt-BR (my language) and pt only. We can use the ietf shortest code rule adding the -SUBCODE only when the necessity arrives. I'm not familiar with Brazil dialect of Portuguese language, but if it's practically different from regular Portuguese, IMO we should use pt-BR as per the standard. We use this code already for Portuguese translation of hbmk2, and I just suspect it was used for good reason. A native speaker is better to make it clear here. All in all, let's use what the standard dictates, and not uniformly xx or uniformly xx-YY. For example, the proper code for Hungarian language is 'hu-HU'. (for generic English it's 'en'). Brgds, Viktor You can find the table here: http://www.iana.org/assignments/language-subtag-registry 2010/2/20 Daniel Gonçalves dan...@base4.com.br: Ok Viktor, I suggested the pattern because on other open-source projects I follow and participate, they use the pattern xx-YY, but I will use the rules for Harbour project. I hope you guys understands that I not trying to impose anything. I'm just trying to help using my knowledge and experience from other spheres! 2010/2/20 Viktor Szakáts harbour...@syenar.hu: It's just a pattern, so we all know that always be xx-YY for ALL languages and not xx for that one and for the other, but for another it is xx-YY, i guess! See! To avoid more things to think about! But this pattern is not true to the standard, it can also be xx, xx-YYY, xx-y-zzz, see the RFC. Each have different and meaningful meanings. I've just made an admonition: en-EN does not exists. I know, that's why I started this discussion in the first place :) If we follow a pattern, it will be one less thing to be concerned about. :-) I think we should follow the standard, rather than a limited pattern. If we invent our own pattern, it will not be possible to interchange our language code with tools which adhere to standards. BTW we should only worry about this _once_ for each language we translate our documentation to. So far we have bits in English and Spanish only, so it's not very complicated. Moreover IMO we should first concentrate on English only. 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 ___ 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
Re: [Harbour] Re: About Harbour Documentation
I am a native pt-BR speaker, and I am web developer also, and here we use pt-BR on the web pages. Of course I like the idea to have pt-BR translation (and contribute too). May we agree in the IETF format? Yes. So to sum it up: Format: NANFORUM Location: root/doc/IETF language code/* Codepage: UTF-8 Some IETF language codes for well-known languages: en - English (generic) pt-BR - Portuguese (Brazil) es - Spanish (generic) hu-HU - Hungarian Maybe we can add the most wanted language folders to the main doc folder and into dirstruc.txt, to serve as example and eliminate the needs for further discussion about this theme. most wanted may be a little premature, given we have not even English docs at the moment :) At least doc/en (just rename back) doc/es doc/pt-BR (maybe some placeholder.txt so it doesnt stay empty) Okay for me. Though I think we should only add the translation dirs only if there is actual content, and for now we should focus on English docs. SVN supports empty dir BTW, so it's not technical issue. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
RE: [Harbour] Re: About Harbour Documentation
Hi all, me and some of my more skilled friends (and programmers) have experienced that the best technical books/docs are always written in english, so I think the documentation has to be written in english (by now). I've also examined the \doc folder and the only subfolder is \en-EN by now: there isn't a folder for spanish documentation (I haven't synched with svn today). Docs in other languages are welcome but I think it's better to have a complete (as possible) documentation, faq, howtos, in english before starting to translate in other languages or we will miss the goal. Best regards, Marco Subject: Re: [Harbour] Re: About Harbour Documentation From: harbour...@syenar.hu Date: Sat, 20 Feb 2010 21:12:31 +0100 To: harbour@harbour-project.org I am a native pt-BR speaker, and I am web developer also, and here we use pt-BR on the web pages. Of course I like the idea to have pt-BR translation (and contribute too). May we agree in the IETF format? Yes. So to sum it up: Format: NANFORUM Location: root/doc/IETF language code/* Codepage: UTF-8 Some IETF language codes for well-known languages: en - English (generic) pt-BR - Portuguese (Brazil) es - Spanish (generic) hu-HU - Hungarian Maybe we can add the most wanted language folders to the main doc folder and into dirstruc.txt, to serve as example and eliminate the needs for further discussion about this theme. most wanted may be a little premature, given we have not even English docs at the moment :) At least doc/en (just rename back) doc/es doc/pt-BR (maybe some placeholder.txt so it doesnt stay empty) Okay for me. Though I think we should only add the translation dirs only if there is actual content, and for now we should focus on English docs. SVN supports empty dir BTW, so it's not technical issue. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour _ Parla, scrivi, gioca... Scopri le novità di Messenger http://www.messenger.it/home_novita.aspx___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi all, me and some of my more skilled friends (and programmers) have experienced that the best technical books/docs are always written in english, so I think the documentation has to be written in english (by now). I've also examined the \doc folder and the only subfolder is \en-EN by now: there isn't a folder for spanish documentation (I haven't synched with svn today). Docs in other languages are welcome but I think it's better to have a complete (as possible) documentation, faq, howtos, in english before starting to translate in other languages or we will miss the goal. Fully agreed, and I haven't created any other language subdirs for now, to remind us that we should focus on English language docs. [ There is some leftover from the paste Spanish documentation in /examples, if there are no objections I will delete those, as they are incomplete and unmaintained since at least 8 years. ] Brgds, Viktor Best regards, Marco Subject: Re: [Harbour] Re: About Harbour Documentation From: harbour...@syenar.hu Date: Sat, 20 Feb 2010 21:12:31 +0100 To: harbour@harbour-project.org I am a native pt-BR speaker, and I am web developer also, and here we use pt-BR on the web pages. Of course I like the idea to have pt-BR translation (and contribute too). May we agree in the IETF format? Yes. So to sum it up: Format: NANFORUM Location: root/doc/IETF language code/* Codepage: UTF-8 Some IETF language codes for well-known languages: en - English (generic) pt-BR - Portuguese (Brazil) es - Spanish (generic) hu-HU - Hungarian Maybe we can add the most wanted language folders to the main doc folder and into dirstruc.txt, to serve as example and eliminate the needs for further discussion about this theme. most wanted may be a little premature, given we have not even English docs at the moment :) At least doc/en (just rename back) doc/es doc/pt-BR (maybe some placeholder.txt so it doesnt stay empty) Okay for me. Though I think we should only add the translation dirs only if there is actual content, and for now we should focus on English docs. SVN supports empty dir BTW, so it's not technical issue. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour La tua privacy è al sicuro con Internet Explorer 8. Scopri di più___ 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
Re: [Harbour] Re: About Harbour Documentation
On Sat, Feb 20, 2010 at 18:43, Marco Boeri boeri...@hotmail.com wrote: Hi all, me and some of my more skilled friends (and programmers) have experienced that the best technical books/docs are always written in english, so I think the documentation has to be written in english (by now). I've also examined Of course, it is the logical starting point. the \doc folder and the only subfolder is \en-EN by now: there isn't a folder for spanish documentation (I haven't synched with svn today). Docs in other languages are welcome but I think it's better to have a complete (as possible) documentation, faq, howtos, in english before starting to translate in other languages or we will miss the goal. I think we agreed in the folder nomenclature at this point only to avoid the need to discus this in the future. Of course you are right, the main documentation should be in English (but if someone decides to contribute right now by translating the few existing docs in any other language, I believe that is not right just forbid it). Best regards, Marco Subject: Re: [Harbour] Re: About Harbour Documentation From: harbour...@syenar.hu Date: Sat, 20 Feb 2010 21:12:31 +0100 To: harbour@harbour-project.org I am a native pt-BR speaker, and I am web developer also, and here we use pt-BR on the web pages. Of course I like the idea to have pt-BR translation (and contribute too). May we agree in the IETF format? Yes. So to sum it up: Format: NANFORUM Location: root/doc/IETF language code/* Codepage: UTF-8 Some IETF language codes for well-known languages: en - English (generic) pt-BR - Portuguese (Brazil) es - Spanish (generic) hu-HU - Hungarian Maybe we can add the most wanted language folders to the main doc folder and into dirstruc.txt, to serve as example and eliminate the needs for further discussion about this theme. most wanted may be a little premature, given we have not even English docs at the moment :) At least doc/en (just rename back) doc/es doc/pt-BR (maybe some placeholder.txt so it doesnt stay empty) Okay for me. Though I think we should only add the translation dirs only if there is actual content, and for now we should focus on English docs. SVN supports empty dir BTW, so it's not technical issue. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour La tua privacy è al sicuro con Internet Explorer 8. Scopri di più ___ 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
RE: [Harbour] Re: About Harbour Documentation
[ There is some leftover from the paste Spanish documentation in /examples, if there are no objections I will delete those, as they are incomplete and unmaintained since at least 8 years. ] I have seen the \es folder in the past but I didn't remember where it was placed. I remember to have examined that and the informations were already dated. I'm not Spanish so I can't vote pro or con, but an 8 years old doc is useless, in my opinion. Best regards, Marco _ Scatta, ritocca e condividi le tue foto online. Gratis per te http://www.windowslive.it/foto.aspx___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
RE: [Harbour] Re: About Harbour Documentation
Of course you are right, the main documentation should be in English (but if someone decides to contribute right now by translating the few existing docs in any other language, I believe that is not right just forbid it). Yes, I see your point and I agree with you. Otherwise I will made a little example: I'm Italian, I could translate the existing documentation for italian users, but I do not, cause the documentation that I will write it will be full of technical and syntactical errors. Simply it will be a waste of time for all of us, not only for me. It would be better if I would write new docs on topic that aren't well documented yet: time well spent. Best regards, Marco _ La tua privacy è al sicuro con Internet Explorer 8. Scopri di più http://www.microsoft.com/italy/windows/internet-explorer/features/browse-privately.aspx?tabid=2catid=1___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Of course you are right, the main documentation should be in English (but if someone decides to contribute right now by translating the few existing docs in any other language, I believe that is not right just forbid it). Yes, I see your point and I agree with you. Otherwise I will made a little example: I'm Italian, I could translate the existing documentation for italian users, but I do not, cause the documentation that I will write it will be full of technical and syntactical errors. Simply it will be a waste of time for all of us, not only for me. It would be better if I would write new docs on topic that aren't well documented yet: time well spent. We should not forbid any translations, and we should think about it for the future, but for now we should _strongly focus_ on English, unless we want to create 3-4 incomplete (but multilanguage!) docs, instead of 1 complete one :) Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
RE: [Harbour] Re: About Harbour Documentation
We should not forbid any translations, and we should think about it for the future, but for now we should _strongly focus_ on English, unless we want to create 3-4 incomplete (but multilanguage!) docs, instead of 1 complete one :) Brgds, Viktor Exactly. I fully agree. By the way I'm not able to write one row of Harbour documentation: it's too far from my skills. Otherwise, if a group (I remember April White and Chen Kedem in the first time) of documentors will need some help for little tasks like proofreader for example, I'm available. ps. It's saturday (not only for me, at least). I'm coming from two days of headache and my job is one light-year far from Clipper-Harbour-xbase dialect, so this is like a hobby for me now and I spent my (little) free time following little web programming and the future of Clipper ... but what about all of you that stay in front of a screen on saturday night Ciao a tutti, Marco _ Parla, scrivi, gioca... Scopri le novità di Messenger http://www.messenger.it/home_novita.aspx___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi all! I have a question that I found when I studied about documentation on NF format and I still can not completely understand: What name we give to new files containing the documentation on SVN? * Respecting the category of functions? * Respecting the category + subcategory? * There is no specific rule? Recalling that this type of nomenclature is important just to keep a certain order in the repository so it will be easy to find and compare the translation between languages of a specific function... because after exporting this data to other formats (web, pdf, etc.) this detail may not seem so important. I think it would be important to mention about it right now ... Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Vailton, On 2010 Feb 21, at 00:15, Vailton Renato wrote: Hi all! I have a question that I found when I studied about documentation on NF format and I still can not completely understand: What name we give to new files containing the documentation on SVN? * Respecting the category of functions? * Respecting the category + subcategory? * There is no specific rule? Recalling that this type of nomenclature is important just to keep a certain order in the repository so it will be easy to find and compare the translation between languages of a specific function... because after exporting this data to other formats (web, pdf, etc.) this detail may not seem so important. Good point. There is no specific rule yet. I think it's better to categorize functions only using keywords (tags) inside doc, otherwise we will have to keep filenames in sync with file content, which in practice will mean a lot cleanup work, and it will never be right. So, maybe the easiest is to create doc filenames from the _beginning_ of functions names (or class names) contained in them: /doc/en/a.txt - containing all A*() functions. /doc/en/bit.txt - containing HB_BIT*() functions. /doc/en/hb_f.txt - containing HB_F*() functions. /doc/en/hb_os.txt - containing HB_OS*() functions. /doc/en/ord.txt - containing ORD*() functions. /doc/en/tbrowse.txt - containing TBROWSE() class. /contrib/hbsqlit3/doc/en/sqlite3.txt - containing all SQLITE3_*() functions. The 'beginning' can the first letter, or first logical section (namespace), of the functions names. (If this is doubtful I can create more examples) This will also create a certain level of natural categorization, since our name are usually well formed, and it makes finding any functions very easy, without the need to grep or do any other sort of multi-file search. Opinions are welcome. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Viktor, [ There is some leftover from the paste Spanish documentation in /examples, if there are no objections I will delete those, as they are incomplete and unmaintained since at least 8 years. ] rant It hard to object if you already deleted them an hour later. You can say that ALL docs are 8 or 10 years old so why don't just delete it all and be done with it. Some of the ES docs where translation of original EN for standard Clipper/Harbour functions. These should not changed in the past 10 years. I know that the docs were neglected, but sometimes it is better to have some reference to work with (future ES documenter) than to have nothing to start with. (I know they are in the SVN tree but for most users they are now gone). /rant *sigh* above were just some ranting because you already deleted them, I have some pending fix requests I made for them dusting in my mailbox for about a decade. So lets continue. Doc function header template can be found in doc/hdr_tpl.txt For start anyone want to contribute anything just post it to the list and if no one else volunteer to act as an editor (preferably a native English speaker) I can try to add them into SVN. Later if we will have enough material to work with, we can try adding some indexing along with doc status (like the funclist.txt we had in the old days). Chen. ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi! As I have proposed to write new HBQt demos, I had an idea today: Maybe the first of them could be a basic visual NanForum command help editor, that scans the correct Harbour folder, hides the NF format for the contributors, by presenting the respective fields as PlainText boxes, and agregate all .txt with $doc$ / $end$ declarations accessible within one interface, so people can stop thinking about the help format and start to write documentation in fact. By doing the properly folder scan, I can extend it to multilanguage also. I developed an tool some months ago that reads all the source code on folder /harbour/src + /harbour/contrib and compare it with the existing documentation in /harbour/doc and show me what has documented and what source files are modified. This tool works as a visual front-end to edit the documentation in the form NF. Additionally wrote an application that reads the format NF and exports to HTML + CSS into an format to integrate the project site ... I just did it as temporary tool, specific to this need and I developed it in Delphi (which is a language I know well) to run on my CPU with Windows and for my needs it is helping me as well, although it lacks some details to be completely ready . Since I could not waste time because our time is short, I opted for that for me it was faster ... Do you think this could be useful in this process? Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Renato can you Publish your delphi source samebody will convert in harbour Is possible a delphi2harbour.ch for convert sample application? 2010/2/19 Vailton Renato vail...@gmail.com: Hi! As I have proposed to write new HBQt demos, I had an idea today: Maybe the first of them could be a basic visual NanForum command help editor, that scans the correct Harbour folder, hides the NF format for the contributors, by presenting the respective fields as PlainText boxes, and agregate all .txt with $doc$ / $end$ declarations accessible within one interface, so people can stop thinking about the help format and start to write documentation in fact. By doing the properly folder scan, I can extend it to multilanguage also. I developed an tool some months ago that reads all the source code on folder /harbour/src + /harbour/contrib and compare it with the existing documentation in /harbour/doc and show me what has documented and what source files are modified. This tool works as a visual front-end to edit the documentation in the form NF. Additionally wrote an application that reads the format NF and exports to HTML + CSS into an format to integrate the project site ... I just did it as temporary tool, specific to this need and I developed it in Delphi (which is a language I know well) to run on my CPU with Windows and for my needs it is helping me as well, although it lacks some details to be completely ready . Since I could not waste time because our time is short, I opted for that for me it was faster ... Do you think this could be useful in this process? -- Massimo Belgrano ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi! 2010/2/19 Massimo Belgrano mbelgr...@deltain.it: Hi Renato can you Publish your delphi source samebody will convert in harbour Is possible a delphi2harbour.ch for convert sample application? I honestly think something like this is hard to happen. I can even post the current code (which lacks some of the details yet) without problems, but I believe that to develop something similar or more specific would only postpone the most important work at the time: start writing the documentation. I ended up riding these tools for their own use without saying a word with the group, just not to open discussion about what GUI or LIB was better to do, just to save time and power and in a short period of time demonstrate the most important: documentation is produced and its outcome on the site. But I see no problems in releasing the code if someone wants to assess, but I am using for some tests on the site before actually produce the documentation itself, I think I need to finish one or two details before releasing the release final. Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
2010/2/19 Vailton Renato vail...@gmail.com: Hi! I honestly think something like this is hard to happen. I can even post the current code (which lacks some of the details yet) without problems, but I believe that to develop something similar or more specific would only postpone the most important work at the time: start writing the documentation. agree I ended up riding these tools for their own use without saying a word with the group, just not to open discussion about what GUI or LIB was better to do, just to save time and power and in a short period of time demonstrate the most important: documentation is produced and its outcome on the site. Very good Still compliment for your final resut But I see no problems in releasing the code if someone wants to assess, but I am using for some tests on the site before actually produce the documentation itself, I think I need to finish one or two details before releasing the release final. Good wait your final detail -- Massimo Belgrano ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
On Fri, Feb 19, 2010 at 08:27, Vailton Renato vail...@gmail.com wrote: Hi! I developed an tool some months ago that reads all the source code on folder /harbour/src + /harbour/contrib and compare it with the existing documentation in /harbour/doc and show me what has documented and what source files are modified. This tool works as a visual front-end to edit the documentation in the form NF. Is this tool in Delphi too? I dont know if we was thinking the same thing, but anyway If yours are in Delphi I still want to do on mine, maybe some part can be used on HBIDE. As both tools work in NanForum format, both tools can be useful without conflicts. I am really focusing on easy of use, handling of all TXTs in doc/LANG and contrib/HBNNN/doc/LANG folders without manual loading, and multilanguage, but mine is starting and yours seems to be done. At least, with your tool and directly into the TXTs maybe someone can start writing documentation right now. Additionally wrote an application that reads the format NF and exports to HTML + CSS into an format to integrate the project site ... I just did it as temporary tool, specific to this need and I developed it in Delphi (which is a language I know well) to run on my CPU with Windows and for my needs it is helping me as well, although it lacks some details to be completely ready . Since I could not waste time because our time is short, I opted for that for me it was faster ... Do you think this could be useful in this process? I was thinking about parse into a database for the web, like mysql+php so we can search for commands online and so on, but this is a future step. For me, the lack of documentation is the true problem. As you already have this temporary tool, I believe that you can use it and share the result files somewere while we don't have another ready for use. Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour Finally, If anyone really want to write documentation, there is no reason to wait for any tool, it's just a matter of pick up any text editor and start writing. Converting it into any other format after is the easy part. Nothing that copy+paste and some little formating won't do (just my opinion, anyway). Regards Bacco ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
The next step will be a sync tool between all TXTs in doc/LANG with a wiki like proposed by Antonio One way not exclude the other 2010/2/19 Bacco carlosba...@gmail.com: On Fri, Feb 19, 2010 at 08:27, Vailton Renato vail...@gmail.com wrote: Hi! Is this tool in Delphi too? I dont know if we was thinking the same thing, but anyway If yours are in Delphi I still want to do on mine, maybe some part can be used on HBIDE. As both tools work in NanForum format, both tools can be useful without conflicts. I am really focusing on easy of use, handling of all TXTs in doc/LANG and contrib/HBNNN/doc/LANG folders without manual loading, and multilanguage, but mine is starting and yours seems to be done. At least, with your tool and directly into the TXTs maybe someone can start writing documentation right now. -- Massimo Belgrano ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi I would like to help to make Official Harbour Documentation a reality. You have been done an excelent coding job here and harbour could be much more appreciated and enjoyed (yet) with a proper official documentation within. Unfortunatelly I have been following that writing Official Harbour Documentation counts on few cabaple heads and requires a lot more hands to be done. I am not sure of how and if this problem can be solved, but I feel like it worths the try to solve it, so I invite you to consider the execution of the following strategy: to form a Harbour Documentation Task Force. The Harbour Documentation Task Force would be conducted by at least three people on the following roles: 1 - Doc Writing Supervisor: writing productivity and the technical quality control of the document writing; 2 - Doc Tools Supervisor: development control of harbour documentation management tools; 3 - Doc Publishing Manager: gramatic and ortografic quality control of the documents, distribuition media and publishing management; 4 - General Coordinator: synchronize and coordinate the work of the 3 task forces; Task force 1 - Doc Writing The only goal of this task force is the most important: to write the text of the harbour documentation. The basic need to acomplish this task is human resources. So to be done this job needs a list of capable volunteers to write the text of the documentation. Considering the huge amount of code to be documented, this task has to be structured in topics. To minimize the debate about how such topic structure should be or look like, the same structure of harbour/src folder could be assumed as the list of topics for a start. Following such logic, documentation writing task would be distributed between Doc Writing Teams, each of which responsible for documenting one or more of the following code 14 topics: 1 - Codepage 2 - Common 3 - Compiler 4 - Debug 5 - Dynlib 6 - Hbextern 7 - Lang 8 - Macro 9 - Main 10 - Nortl 11 - PP, rdd, rtl and vm. There must be chosen a Doc Writing coordinator to synchronize this task to the general chronogram and supervise the quality of the writing. The first job this person should take care could be the calculation of how many teams (of how many people each) should be necessary to write the documentation of above 14 topics, considering the technical afinity among some of the topics and their weight differences, once some can have much more to be documented than others. Once that is defined, the following would be to recruit such amount of volunteers and allocate them to their tasks. Task force 2 - Doc Editing Tool This task force would initially develop a tool to make Doc Writing more organized and productive. Such tool should provide: 1 - documentation task status, comparing of harbour source files to harbour document files, classified by source folder; 2 - easy and simple interface to edit documents, so writers don't need to know or care about folders, files, markers etc, only about the text; 3 - document status control interface, where Doc Writing coordinator can sinalize and Doc Writers can see what documents are (and weather each document is) done, not started, incomplete or not good; Much of what it takes to provide the above seems to have been already achieved by Vailton using Delphy and they can be written in harbour. -- From: Bacco carlosba...@gmail.com Sent: Friday, February 19, 2010 9:56 AM To: Harbour Project Main Developer List. harbour@harbour-project.org Subject: Re: [Harbour] Re: About Harbour Documentation On Fri, Feb 19, 2010 at 08:27, Vailton Renato vail...@gmail.com wrote: Hi! I developed an tool some months ago that reads all the source code on folder /harbour/src + /harbour/contrib and compare it with the existing documentation in /harbour/doc and show me what has documented and what source files are modified. This tool works as a visual front-end to edit the documentation in the form NF. Is this tool in Delphi too? I dont know if we was thinking the same thing, but anyway If yours are in Delphi I still want to do on mine, maybe some part can be used on HBIDE. As both tools work in NanForum format, both tools can be useful without conflicts. I am really focusing on easy of use, handling of all TXTs in doc/LANG and contrib/HBNNN/doc/LANG folders without manual loading, and multilanguage, but mine is starting and yours seems to be done. At least, with your tool and directly into the TXTs maybe someone can start writing documentation right now. Additionally wrote an application that reads the format NF and exports to HTML + CSS into an format to integrate the project site ... I just did it as temporary tool, specific to this need and I developed it in Delphi (which is a language I know well) to run on my CPU with Windows and for my needs it is helping me as well, although it lacks some details to be completely ready . Since I could
Re: [Harbour] Re: About Harbour Documentation
revision (grammar, ortography, etc) of the document texts, as weel as the aesthetics and text style considerations. Of course some of this job can be started right away, but sure its no sense at all to talk much about it before the documents start to be written. Once there is a documentation written, the Doc Publishing Manager will can also start to recruit translators of the documents to other languages beyond English, when I'd be glad to candidate to the Brazillian Portuguese Doc Version team. Doc Task Coordination The initial job of the Doc Task Coordinator would be to determine with the team managers the chronogram that will state the date when the Harbour Official Documentation Task Force will begin to operate and the steps following this start date. Of course this just could happen after the coordinator and the managers volunteer, be chosen and assume their roles. Sorry if I this is an inconvenient proposal. I'm aware Harbour-Project is not a company and that nobody is paid for any participation or has the obligation to do anything. Let me know if there is something else I can do to help. Best regards, Leandro Damasio -- From: Bacco carlosba...@gmail.com Sent: Friday, February 19, 2010 9:56 AM To: Harbour Project Main Developer List. harbour@harbour-project.org Subject: Re: [Harbour] Re: About Harbour Documentation On Fri, Feb 19, 2010 at 08:27, Vailton Renato vail...@gmail.com wrote: Hi! I developed an tool some months ago that reads all the source code on folder /harbour/src + /harbour/contrib and compare it with the existing documentation in /harbour/doc and show me what has documented and what source files are modified. This tool works as a visual front-end to edit the documentation in the form NF. Is this tool in Delphi too? I dont know if we was thinking the same thing, but anyway If yours are in Delphi I still want to do on mine, maybe some part can be used on HBIDE. As both tools work in NanForum format, both tools can be useful without conflicts. I am really focusing on easy of use, handling of all TXTs in doc/LANG and contrib/HBNNN/doc/LANG folders without manual loading, and multilanguage, but mine is starting and yours seems to be done. At least, with your tool and directly into the TXTs maybe someone can start writing documentation right now. Additionally wrote an application that reads the format NF and exports to HTML + CSS into an format to integrate the project site ... I just did it as temporary tool, specific to this need and I developed it in Delphi (which is a language I know well) to run on my CPU with Windows and for my needs it is helping me as well, although it lacks some details to be completely ready . Since I could not waste time because our time is short, I opted for that for me it was faster ... Do you think this could be useful in this process? I was thinking about parse into a database for the web, like mysql+php so we can search for commands online and so on, but this is a future step. For me, the lack of documentation is the true problem. As you already have this temporary tool, I believe that you can use it and share the result files somewere while we don't have another ready for use. Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour Finally, If anyone really want to write documentation, there is no reason to wait for any tool, it's just a matter of pick up any text editor and start writing. Converting it into any other format after is the easy part. Nothing that copy+paste and some little formating won't do (just my opinion, anyway). Regards Bacco ___ 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
Re: [Harbour] Re: About Harbour Documentation
Hi all I would like to help to make Official Harbour Documentation a reality. You have been done an excelent coding job here and harbour could be much more appreciated and enjoyed (yet) with a proper official documentation within. Unfortunatelly I have been following that writing Official Harbour Documentation counts on few cabable heads and requires a much more of their two hands to be done. I am not sure of how and if this problem can be solved, but I feel like it worths the try to solve it, so I invite you to consider the execution of the following strategy: to form a Harbour Documentation Task Force. The Harbour Documentation Task Force would be conducted by at least 4 people on the following roles: 1 - Doc Writing Supervisor: writing productivity and the technical quality control of the document writing; 2 - Doc Tools Supervisor: development control of harbour documentation management tools; 3 - Doc Publishing Manager: gramatic and ortografic quality control of the documents, distribuition media and publishing management; 4 - General Coordinator: synchronize and coordinate the work of the 3 task forces; Task force 1 - Doc Writing The only goal of this task force is the most important of all: to write the text of the harbour documentation. The basic need to acomplish this task is human resources. So to be done this job needs a list of capable volunteers to write the text of the documentation. Considering the huge amount of code to be documented, this task has to be structured in topics. To minimize the debate about how such topic structure should be or look like, the same structure of harbour/src folder could be assumed as the list of topics for a start. Following such logic, documentation writing task would be distributed between Doc Writing Teams, each of which responsible for documenting one or more of the following code 14 topics: 1 - Codepage 2 - Common 3 - Compiler 4 - Debug 5 - Dynlib 6 - Hbextern 7 - Lang 8 - Macro 9 - Main 10 - Nortl 11 - PP 12- RDD 13 - RTL 14 - VM. There must be chosen a Doc Writing coordinator to synchronize this task to the general chronogram and supervise the quality of the writing. The first job this person should take care could be the calculation of how many teams (of how many people each) should be necessary to write the documentation of above 14 topics, considering the technical afinity among some of the topics and their weight differences, once some can have much more to be documented than others. Once that is defined, the following job would be to recruit such amount of volunteers and allocate them to their tasks. Task force 2 - Doc Tools This task force would initially develop a tool to make Doc Writing more organized and productive. Such tool should initially provide : 1 - documentation task status, comparing of harbour source files to harbour document files, classified by source folder; 2 - easy and simple interface to edit documents, so writers don't need to know or care about folders, files, markers etc, only about the text; 3 - document status control interface, where Doc Writing coordinator can sinalize and Doc Writers can see what documents are (and weather each document is) done, not started, incomplete or not good; Much of what it takes to provide the above goods seems to have been already achieved by Vailton using Delphy and of course they can be done also using Harbour. I'm sure this is the task force that can be formed earlier, because most people here can code, but we must consider that, without a capable team responsible for writing the docs there is not much sense to build such tools. Anyway, I believe the the 1st item could help very much on the work Doc Writers recruiting, because once people know what exactly is to be written on each topic, it would be easier that they can candidate to write about this and that and maybe this task should be done in first place anyways. Of course a lot of other things sure would be asked from Doc Tools team in future, but I believe the above would be enough for the beginning. Task force 3 - Doc Publishing This task force would be responsible for determining the better distribution formats and publishing media and care for the gramatical and ortografical quality of the document text, as weel as all the aesthetic and text style considerations. Of course some of this job can be started right away, but sure its no sense at all to talk much about it before the documents start to be written. Sorry if I this was inconvenient and let me know if there is something else I can do to help. Best regards to all Leandro -- From: Bacco carlosba...@gmail.com Sent: Friday, February 19, 2010 9:56 AM To: Harbour Project Main Developer List. harbour@harbour-project.org Subject: Re: [Harbour] Re: About Harbour Documentation On Fri, Feb 19, 2010 at 08:27, Vailton Renato vail...@gmail.com wrote: Hi! I developed
[Harbour] Re: About Harbour Documentation
στις 18/02/2010 17:27, O/H Viktor Szakáts έγραψε: Hi All, So, I'd like to ask prospective contributors to _ignore these_ and concentrate on our path. It has been said many times: There will only be a documentation (in any format, or medium), if someone actually writes them. There is no other way. Ok, let's (try to) write some documentation. But before we start we have to know, what format should adopt. I mean, is Nanforum format mandatory or we could follow a more human form? For example, I am going to start documenting the functions HB_DirExists(), HB_FileExists(), HB_FNameExists() found into src\rtl\hbfile.c I choose to reproduce the structure of, say, doc\en-EN\dir.txt, hence i have to write something like: /* * The following parts are Copyright of the individual authors. * www - http://www.harbour-project.org * * Copyright 2010 documentor's_name m...@myoffice.gr *Documentation for: HB_DirExists(), HB_FileExists(), HB_FNameExists() * * See COPYING for licensing terms. * */ /* $DOC$ * $TEMPLATE$ * Function * $NAME$ * HB_DirExists() * $CATEGORY$ * API * $SUBCATEGORY$ * FileSys * $ONELINER$ * Determine if a directory exists * $SYNTAX$ * HB_DirExists( [cDirName] ) -- lExists * $ARGUMENTS$ * cDirName Directory name you want to check if exist. * Can contain a path and Drive letter. * Wildcards are NOT supported. * If no path specified then the current path is used. * SET DEFAULT are not evaluated. * $RETURNS$ * HB_DirExists returns a logical TRUE if cDirName exists, otherwise FALSE * $DESCRIPTION$ *Here goes a detailed and very time consuming 'bla-bla' about the function *for which bla-bla is better to been left for the second documantation wave *and why not as an imagination exercise for the potential reader) * * $EXAMPLES$ * #include 'common.ch' * Function Main( cDir ) *Default cDir to lib *QOUT(Current directory:CurDir() ) *QOUT(--) *QOUT( Directory:cDirdoes IIF( HB_DirExists(cDir), , NOT ) exist! ) *cDir := C:\ *QOUT( Directory:cDirdoes IIF( HB_DirExists(cDir), , NOT ) exist! ) *QOUT() *WAIT *RETURN Nil * * $STATUS$ * R * $COMPLIANCE$ * C * $PLATFORMS$ * All(LFN) * $FILES$ * Library is rtl * $SEEALSO$ * HB_FileExists(), HB_FNameExists() * $END$ */ Now i have one/two more questions: Are all those eye-bothering '$' '*' necesary? Also, are _all_ the above statements mandatory or we could leave out some of them like $SUBCATEGORY$ $STATUS$ $COMPLIANCE$ etc. to make the txt more compact and 'quick-readable' Supposing the answers are 'yes' let see how the above document could be written: -- /* $DOC$ FUNCNAME : HB_DirExists( cDirName ) -- lExists SHORTDESC : Determine if a directory exists ARGUMENTS : cDirName Directory name you want to check if exist. Can contain a path and Drive letter. Wildcards are NOT supported. If no path specified then the current path is used. SET DEFAULT are not evaluated. RETURNS : HB_DirExists returns a logical TRUE if cDirName exists, otherwise FALSE DESCRIPTION: [Here goes a detailed and very time consuming 'bla-bla' about the function for which bla-bla is better to left for the second documantation wave (and why not as an imagination exersize for the potential reader) ... ...] EXAMPLES: #include 'common.ch' Function Main( cDir ) Default cDir to lib QOUT(Current directory:CurDir() ) QOUT(--) QOUT( Directory:cDirdoes IIF( HB_DirExists( cDir ), , NOT ) exist! ) cDir := C:\ QOUT( Directory:cDirdoes IIF( HB_DirExists( cDir ), , NOT ) exist! ) QOUT() WAIT RETURN Nil PLATFORMS: All(LFN) FILES: Library is rtl SEE ALSO: HB_FileExists(), HB_FNameExists() $END$ */ An other critical question is how do i decide to document what? That is, how do I know if the above documentation is not already written by someone else? Obviously, somebody has to monitor the whole process, keeping an eye on 'who is documenting what' to avoid overlapping writing. And of course, there are other things/questions that must be cleared up, but can't been discussed all at once.. regards, --- Pete ___ Harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Pete, Ok, let's (try to) write some documentation. But before we start we have to know, what format should adopt. I mean, is Nanforum format mandatory or we could follow a more human form? No, Nanforum format is mandatory. /* $DOC$ * $TEMPLATE$ * Function * $NAME$ * HB_DirExists() * $CATEGORY$ ... * $END$ */ Now i have one/two more questions: Are all those eye-bothering '$' '*' necesary? Also, are _all_ the above statements mandatory or we could leave out some of them like $SUBCATEGORY$ $STATUS$ $COMPLIANCE$ etc. to make the txt more compact and 'quick-readable' Supposing the answers are 'yes' let see how the above document could be written: It could be written in any way, but then you'd need to create parsers for each format ppl happened to use. We've choosen NANFORUM format, because it is already developed, fits our purpose, easy to use, and we have already created tools that can process it. Our goal in this project is _not_ to invent or reinvent a new documentation format. Our goal is to document Harbour functions using an existing _standard_. This standard is NANFORUM. -- An other critical question is how do i decide to document what? That is, how do I know if the above documentation is not already written by someone else? Obviously, somebody has to monitor the whole process, keeping an eye on 'who is documenting what' to avoid overlapping writing. It's simple: If something is not present in /doc/en-EN/ folder, it's safe to document. (Even if it's present, it can probably need a review/rewrite.) who writes what: It requires some very basic synchronization between documentation writers. I don't think we should develop some over-burocratic scheme for this yet. If someone is starting seriously on a given lib or set of source files, it's enough to drop here an e-mail. At the time when this becomes inadequate, we can use a simple text file on wiki or in SVN, called TODODOC.txt or similar. This file can have each Harbour function, grouped by source file, with a status: TODO [username] - DONE [username] - CHECKED [username] Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
For example, suppose I want to contribute documenting the hbsqlit3 contrib, wich is module I'm very interested. What I'm suposed to do? Create a directory /harbour/doc/en-EN/contrib/hbsqlit3 and write text files in NF format? 2010/2/19 Massimo Belgrano mbelgr...@deltain.it: The next step will be a sync tool between all TXTs in doc/LANG with a wiki like proposed by Antonio One way not exclude the other 2010/2/19 Bacco carlosba...@gmail.com: On Fri, Feb 19, 2010 at 08:27, Vailton Renato vail...@gmail.com wrote: Hi! Is this tool in Delphi too? I dont know if we was thinking the same thing, but anyway If yours are in Delphi I still want to do on mine, maybe some part can be used on HBIDE. As both tools work in NanForum format, both tools can be useful without conflicts. I am really focusing on easy of use, handling of all TXTs in doc/LANG and contrib/HBNNN/doc/LANG folders without manual loading, and multilanguage, but mine is starting and yours seems to be done. At least, with your tool and directly into the TXTs maybe someone can start writing documentation right now. -- Massimo Belgrano ___ 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
Re: [Harbour] Re: About Harbour Documentation
For example, suppose I want to contribute documenting the hbsqlit3 contrib, wich is module I'm very interested. What I'm suposed to do? Create a directory /harbour/doc/en-EN/contrib/hbsqlit3 and write text files in NF format? All contribs are meant to be independent from core, so their docs should be stored in /contrib/name/doc/en-EN/* [similar to already existing documentation for 'rddads'] Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: About Harbour Documentation
Viktor Szakáts wrote: No, Nanforum format is mandatory. /* $DOC$ * $TEMPLATE$ * Function * $NAME$ * HB_DirExists() * $CATEGORY$ ... * $END$ */ How many keywords are there in this format ? Probably a basic implementation can be provided in hbIDE within a couple of days. And later Bacco's or Vailton's tool will be pressed into service. hbIDE can parse the source and can provide readymade templates to be filled in by the writer. When saved, it will be in above format. Should I proceed ? - enjoy hbIDEing... Pritpal Bedi _a_student_of_software_analysis__design_ -- View this message in context: http://n2.nabble.com/About-Harbour-Documentation-tp4587608p4601441.html Sent from the harbour-devel mailing list archive at Nabble.com. ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Pete. I am writing a tool that will hide all eye-bothering features you have mentioned at the edit time. It's an optional tool, but It will agregate access to all docs directory tree (as they are already specified in doc/dirstruc.txt) from a single interface, and provide separated fields for each entry. The /*, $DOC$ etc in the output file will be created by the tool when you include a new command. Also, by scanning all doc dirs, It will be able to list and do a quick search in all documented commands, without the need to loading one by one, so writers can start writing a missing command with a single click. On Fri, Feb 19, 2010 at 19:15, pete_westg pete_we...@yahoo.gr wrote: στις 18/02/2010 17:27, O/H Viktor Szakáts έγραψε: Hi All, So, I'd like to ask prospective contributors to _ignore these_ and concentrate on our path. It has been said many times: There will only be a documentation (in any format, or medium), if someone actually writes them. There is no other way. Ok, let's (try to) write some documentation. But before we start we have to know, what format should adopt. I mean, is Nanforum format mandatory or we could follow a more human form? For example, I am going to start documenting the functions HB_DirExists(), HB_FileExists(), HB_FNameExists() found into src\rtl\hbfile.c I choose to reproduce the structure of, say, doc\en-EN\dir.txt, hence i have to write something like: /* * The following parts are Copyright of the individual authors. * www - http://www.harbour-project.org * * Copyright 2010 documentor's_name m...@myoffice.gr * Documentation for: HB_DirExists(), HB_FileExists(), HB_FNameExists() * * See COPYING for licensing terms. * */ /* $DOC$ * $TEMPLATE$ * Function * $NAME$ * HB_DirExists() * $CATEGORY$ * API * $SUBCATEGORY$ * FileSys * $ONELINER$ * Determine if a directory exists * $SYNTAX$ * HB_DirExists( [cDirName] ) -- lExists * $ARGUMENTS$ * cDirName Directory name you want to check if exist. * Can contain a path and Drive letter. * Wildcards are NOT supported. * If no path specified then the current path is used. * SET DEFAULT are not evaluated. * $RETURNS$ * HB_DirExists returns a logical TRUE if cDirName exists, otherwise FALSE * $DESCRIPTION$ * Here goes a detailed and very time consuming 'bla-bla' about the function * for which bla-bla is better to been left for the second documantation wave * and why not as an imagination exercise for the potential reader) * * $EXAMPLES$ * #include 'common.ch' * Function Main( cDir ) * Default cDir to lib * QOUT(Current directory: CurDir() ) * QOUT(--) * QOUT( Directory: cDir does IIF( HB_DirExists(cDir), , NOT ) exist! ) * cDir := C:\ * QOUT( Directory: cDir does IIF( HB_DirExists(cDir), , NOT ) exist! ) * QOUT() * WAIT * RETURN Nil * * $STATUS$ * R * $COMPLIANCE$ * C * $PLATFORMS$ * All(LFN) * $FILES$ * Library is rtl * $SEEALSO$ * HB_FileExists(), HB_FNameExists() * $END$ */ Now i have one/two more questions: Are all those eye-bothering '$' '*' necesary? Also, are _all_ the above statements mandatory or we could leave out some of them like $SUBCATEGORY$ $STATUS$ $COMPLIANCE$ etc. to make the txt more compact and 'quick-readable' Supposing the answers are 'yes' let see how the above document could be written: -- /* $DOC$ FUNCNAME : HB_DirExists( cDirName ) -- lExists SHORTDESC : Determine if a directory exists ARGUMENTS : cDirName Directory name you want to check if exist. Can contain a path and Drive letter. Wildcards are NOT supported. If no path specified then the current path is used. SET DEFAULT are not evaluated. RETURNS : HB_DirExists returns a logical TRUE if cDirName exists, otherwise FALSE DESCRIPTION: [Here goes a detailed and very time consuming 'bla-bla' about the function for which bla-bla is better to left for the second documantation wave (and why not as an imagination exersize for the potential reader) ... ...] EXAMPLES: #include 'common.ch' Function Main( cDir ) Default cDir to lib QOUT(Current directory: CurDir() ) QOUT(--) QOUT( Directory: cDir does IIF( HB_DirExists( cDir ), , NOT ) exist! ) cDir := C:\ QOUT( Directory: cDir does IIF(
Re: [Harbour] Re: About Harbour Documentation
IMHO, it would be simpler to create a simple tool to parse the NanForum format into a database, for example. From the database, we could use php into a site to show and search the documentation, and so on. The same kind of tools could generate many other formats, suitable to other uses. If someday we leave the NF format, I believe that would be better to use more powerful ways to organize the structured data for documentation. Note that I am not underestimating the power of Sphinx, but it just seemed too texty to justify the migration. Exactly. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Ok! I agree. I'm searching for NanForum file format and google didn't give me any usefull results. I search for hbdoc2 in the harbour sources, but I can't found. Where is hbdoc2 and where can I found information about NanForum file format? Regards! 2010/2/18 Viktor Szakáts harbour...@syenar.hu: IMHO, it would be simpler to create a simple tool to parse the NanForum format into a database, for example. From the database, we could use php into a site to show and search the documentation, and so on. The same kind of tools could generate many other formats, suitable to other uses. If someday we leave the NF format, I believe that would be better to use more powerful ways to organize the structured data for documentation. Note that I am not underestimating the power of Sphinx, but it just seemed too texty to justify the migration. Exactly. 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
Re: [Harbour] Re: About Harbour Documentation
Hi Daniel, Ok! I agree. I'm searching for NanForum file format and google didn't give me any usefull results. I search for hbdoc2 in the harbour sources, but I It's in /examples/hbdoc2/ can't found. Where is hbdoc2 and where can I found information about NanForum file format? I'd suggest to check existing files in /doc/en-EN/*.txt It's also worth checking /examples/hbdoc2/tmplates.prg, which is the actual parser for the format, to get an idea about all recognized sections and keywords. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Why don't we use a wiki for the documentation ? :-) We have been using a wiki for several years and we are very happy with the results. Our wiki of choice is Dokuwiki as it just uses plain text files. No database required. Here you have several examples: http://wiki.fivetechsoft.com/doku.php?id=fivewin_commands_activexs=tactivex http://wiki.fivetechsoft.com/doku.php?id=fivewin_class_tactivex Our documentation has improved very much since we decided to start using a wiki. Antonio ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Many times when a user ask for a question is as easy as write the answer into the wiki and then point the user to the wiki entry. So instead of writting messages on the list that answer the same topic again and again, the wiki gets more and more completed. Wiki is safe against vandalism, and whoever wants to participate is welcome to do it :-) ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Functions alphabetically ordered: http://wiki.fivetechsoft.com/doku.php?id=fivewin_functions_alphabetically_ordered Classes alphabetically ordered: http://wiki.fivetechsoft.com/doku.php?id=fivewin_classes_alphabetically_ordered Commands alphabetically ordered: http://wiki.fivetechsoft.com/doku.php?id=fivewin_commands_alphabetically_ordered As you can see DokuWiki is a great tool for collaborative documentation of a project :-) best regards, Antonio ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi All, First about wiki: - Wiki is really a final/presentation format in context of Harbour. Easy to convert _to_, but very difficult to convert _from_. That makes it a target format rather than a source format. - How to convert wiki page to usable .pdf, .rtf? - Wiki has no standard source format. So we must also choose one specific implementation, which is usually a never ending debate. - I personally like MediaWiki format f.e., that's what wikipedia uses, too. Yet many ppl are not familiar even with this one, and the package is pretty difficult to host anyway. - Any wiki solution needs to be hosted somewhere. We had a Wiki on sf.net, but it was slow. We have a Wiki in Trac on sf.net since years: nobody uses it. Maybe we could have MediaWiki on sf.net, but results are doubtful. Not to mention our wikipedia page, which no one touches, and looks shameful. - How to distribute Wiki pages as part of Harbour source package? - If above point is somehow solved, how to easily view it? I like Wiki very much, but for Harbour doc source it's not good solution. BTW, I can't question anybody's intent, but every time we see a chance for real contribution for documentation, I see some someone accidentally popping in with a revolutionary idea (last time we got an offer to buy one for 30 something thousand dollars). The result was so far always confusion and fading interest. So, I'd like to ask prospective contributors to _ignore these_ and concentrate on our path. It has been said many times: There will only be a documentation (in any format, or medium), if someone actually writes them. There is no other way. Brgds, Viktor On 2010 Feb 18, at 11:42, Antonio Linares wrote: Why don't we use a wiki for the documentation ? :-) We have been using a wiki for several years and we are very happy with the results. Our wiki of choice is Dokuwiki as it just uses plain text files. No database required. Here you have several examples: http://wiki.fivetechsoft.com/doku.php?id=fivewin_commands_activexs=tactivex http://wiki.fivetechsoft.com/doku.php?id=fivewin_class_tactivex Our documentation has improved very much since we decided to start using a wiki. Antonio ___ 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
Re: [Harbour] Re: About Harbour Documentation
Viktor, DokuWiki uses a plain text (ascii) file for each wiki page. i.e. see this function: http://wiki.fivetechsoft.com/doku.php?id=fivewin_function_abortdoc This is the ascii file stored for it: == AbortDoc() == Stop a print job == Syntax: == AbortDoc(hDC ) -- nSuccess == Parameters: == | hDC | Device context for the print job. | == Returns: == | nSuccess | Return value is greater than zero if the function is successful. | == Sample: == == Source Code: == SOURCE\WINAPI\PRINTDC.C As you can see, we can easily import to DokuWiki or export from it. In fact, our initial version was exported from our help files and imported as docuwiki pages using a simple Harbour app :-) Anyhow, I am not trying to convince anybody here. I just exposing my own experience about documentation. Meanwhile there is not an easy and quick way to update the docs, they will always be outdated. Even using a wiki, we have to do an effort to keep it updated :-) ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
I think that what docuwiki does, we already have. Most of us can write some prg to convert NF to docuwiki. Its not so hard to make a parser to exhibit the NF as wiki on the web instead of exchange text to another text, OR we shoud move to more complex structures to justify the change. As I have proposed to write new HBQt demos, I had an idea today: Maybe the first of them could be a basic visual NanForum command help editor, that scans the correct Harbour folder, hides the NF format for the contributors, by presenting the respective fields as PlainText boxes, and agregate all .txt with $doc$ / $end$ declarations accessible within one interface, so people can stop thinking about the help format and start to write documentation in fact. By doing the properly folder scan, I can extend it to multilanguage also. Opinions are welcome. Regards On Thu, Feb 18, 2010 at 14:17, Antonio Linares antonioharb...@gmail.com wrote: Viktor, DokuWiki uses a plain text (ascii) file for each wiki page. i.e. see this function: http://wiki.fivetechsoft.com/doku.php?id=fivewin_function_abortdoc This is the ascii file stored for it: == AbortDoc() == Stop a print job == Syntax: == AbortDoc(hDC ) -- nSuccess == Parameters: == | hDC | Device context for the print job. | == Returns: == | nSuccess | Return value is greater than zero if the function is successful. | == Sample: == == Source Code: == SOURCE\WINAPI\PRINTDC.C As you can see, we can easily import to DokuWiki or export from it. In fact, our initial version was exported from our help files and imported as docuwiki pages using a simple Harbour app :-) Anyhow, I am not trying to convince anybody here. I just exposing my own experience about documentation. Meanwhile there is not an easy and quick way to update the docs, they will always be outdated. Even using a wiki, we have to do an effort to keep it updated :-) ___ 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
[Harbour] Re: About Harbour Documentation
Bacco wrote: As I have proposed to write new HBQt demos, I had an idea today: Maybe the first of them could be a basic visual NanForum command help editor, that scans the correct Harbour folder, hides the NF format for the contributors, by presenting the respective fields as PlainText boxes, and agregate all .txt with $doc$ / $end$ declarations accessible within one interface, so people can stop thinking about the help format and start to write documentation in fact. By doing the properly folder scan, I can extend it to multilanguage also. This will be cool. Also the tool will be portable and hence evrybody could submit help files, one per function, or so, created with this tool. Someonw will have to organize them in SVN. - enjoy hbIDEing... Pritpal Bedi _a_student_of_software_analysis__design_ -- View this message in context: http://n2.nabble.com/About-Harbour-Documentation-tp4587608p4593815.html Sent from the harbour-devel mailing list archive at Nabble.com. ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi Bacco, I think that what docuwiki does, we already have. Most of us can write some prg to convert NF to docuwiki. Its not so hard to make a parser to exhibit the NF as wiki on the web instead of exchange text to another text, OR we shoud move to more complex structures to justify the change. As I have proposed to write new HBQt demos, I had an idea today: Maybe the first of them could be a basic visual NanForum command help editor, that scans the correct Harbour folder, hides the NF format for the contributors, by presenting the respective fields as PlainText boxes, and agregate all .txt with $doc$ / $end$ declarations accessible within one interface, so people can stop thinking about the help format and start to write documentation in fact. By doing the properly folder scan, I can extend it to multilanguage also. Opinions are welcome. Good idea. With the only addition, that we should not require HBQT to edit any of our doc files, but if we have such editor/viewer tool as extra option, it's all the better. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
The HBQt tool will be only a front-end to already existing NF TXTs and will create new ones based on the template, so contributors can choose to still edit the TXTs directly, or use this visual tool as they want. I proposed to do as a demo of HBQt, so I can be realist and finish the job, as I know that will focus on the inner workings, instead of worrying about the interface. In fact, I am thinking about the consequences and subproducts of this tool, not only the tool itself. So, lets go then! Regards, Bacco On Thu, Feb 18, 2010 at 17:31, Viktor Szakáts harbour...@syenar.hu wrote: Hi Bacco, Good idea. With the only addition, that we should not require HBQT to edit any of our doc files, but if we have such editor/viewer tool as extra option, it's all the better. Brgds, Viktor ___ 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
Re: [Harbour] Re: About Harbour Documentation
Hi, What do you think? Regards, Vailton Renato Nice ! Two questions comes to mind... 2) What would be the methodology to update harbour/doc files in a collaborative way ? They should be committed to SVN just like code changes. Either directly by authors (if they have R/W access) or by someone who aggregates the work of certain authors. If there is any volunteer for this aggregation task we can grant R/W access, if other admins also agree. If this is to cumbersome for a start, we may simply gather .txt files somewhere, and commit them from time to time to SVN. I've done a searh for hb_ functions only on harbour tree and I got 888 ocurrences. And we are talking about harbour extensions alone. So there must be a way to divide tasks among many volunteers and a DocMaster reviewing and aproving submitted documents. This DocMaster need not only excelent English languaje skills but also deep knowledge of Harbour internals and some ability to read C code. Since we don't appear to have a Doc Master at the moment, and I wouldn't really block any documentation effort by looking for one, I think the process just has to be started. Who starts with which section? is enough to decide at this point. As for a (non-visual!) style guideline for the docs, I think it's just perfect if we follow the path of Hannes Ziegler with xhb and Xbase++ docs. my 2 cents, that is. Brgds, Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
Hi! 1) What is wxweb ? It shows a list of functions but tells nothing about what is or how to use it. If the wxWeb is a LIB for programming CGI and ISAPI I developed some years ago for use with XHB and I'm porting it to HB. It is free and open source: http://code.google.com/p/wxweb/ 2) What would be the methodology to update harbour/doc files in a collaborative way ? I was initially based on hbextern me to know which functions initially document. But I imagine that we could feed the DOC via SVN folder and use something like hbdoc2 (or something similar) to update the site. Initially I would be writing the texts in English ... if they were in Portuguese, the work would flow much faster because it is my native language, but I think we should support the project and there is no way to ignore the relevance of English. Regards, Vailton Renato ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
In harbour user group we have an interesting event relating to harbour doc Daniel Gonçalves have give his availability for give us a path for Having Documentation http://www.mail-archive.com/harbour-us...@harbour-project.org/msg00335.html so now i suggest a common way between way of Daniel Gonçalves and Vailton renato (that is very good,compliment) i give also my aivability to translate in italian (is the only thing tha i able to do with good result) 2010/2/17 Viktor Szakáts harbour...@syenar.hu Hi, What do you think? Regards, Vailton Renato Nice ! Two questions comes to mind... 2) What would be the methodology to update harbour/doc files in a collaborative way ? They should be committed to SVN just like code changes. Either directly by authors (if they have R/W access) or by someone who aggregates the work of certain authors. If there is any volunteer for this aggregation task we can grant R/W access, if other admins also agree. If this is to cumbersome for a start, we may simply gather .txt files somewhere, and commit them from time to time to SVN. I've done a searh for hb_ functions only on harbour tree and I got 888 ocurrences. And we are talking about harbour extensions alone. So there must be a way to divide tasks among many volunteers and a DocMaster reviewing and aproving submitted documents. This DocMaster need not only excelent English languaje skills but also deep knowledge of Harbour internals and some ability to read C code. Since we don't appear to have a Doc Master at the moment, and I wouldn't really block any documentation effort by looking for one, I think the process just has to be started. Who starts with which section? is enough to decide at this point. As for a (non-visual!) style guideline for the docs, I think it's just perfect if we follow the path of Hannes Ziegler with xhb and Xbase++ docs. my 2 cents, that is. Brgds, Viktor -- Massimo Belgrano ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
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. -- Massimo Belgrano ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
RE: [Harbour] Re: About Harbour Documentation
Hi First-timer on users list. If this helps in any way, pages auto generated from the Harbour source tree ( a little older ) but depicts some usage can be achieved: http://harbour.vouch.info/ Regards Pritpal Bedi, a student of software analysis and design http://www.vouch.in | Vouch, the software that GROWS with you http://www.vouch32.com | Home of Vouch32 ActiveX Server http://www.vouchcac.com/vouch32/vouch32.htm | A Free Windows Extended Utilities Library for Clipper, Xbase++ and (x)Harbour http://www.help.vouch.info | Online Vouch Help http://www.harbour.vouch.info | Online Harbour Help _ Hotmail: Trusted email with powerful SPAM protection. http://clk.atdmt.com/GBL/go/201469227/direct/01/___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: About Harbour Documentation
IMHO, it would be simpler to create a simple tool to parse the NanForum format into a database, for example. From the database, we could use php into a site to show and search the documentation, and so on. The same kind of tools could generate many other formats, suitable to other uses. If someday we leave the NF format, I believe that would be better to use more powerful ways to organize the structured data for documentation. Note that I am not underestimating the power of Sphinx, but it just seemed too texty to justify the migration. Just my opinion, of course. 2010/2/18 Daniel Gonçalves dan...@base4.com.br: 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
