[YAM - Yet Another Mailer] Topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/topic/109 <p> Online documentation and wiki formatting </p> en-us YAM - Yet Another Mailer http://yam.ch/chrome/site/yam.gif http://yam.ch/discussion/topic/109 Trac 1.0.1 - DiscussionPlugin AmigaPhil Sat, 28 Sep 2013 19:56:54 GMT Topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/topic/109#topic http://yam.ch/discussion/topic/109#topic <p> Hello, </p> <p> I don't understand how to create and edit the "post-it" on wiki pages. It looks like a include instruction, but I don't find where to edit the contents. </p> <p> For example, I tried to add 2 more languages (Français and Español) on the Languages "post-it" of the main documentation page, but when editing that page, I only see a "[[TranslatedPages]]" link and can't find that TranslatedPages document. </p> <p> ? </p> Topic AmigaPhil Tue, 22 Oct 2013 18:00:50 GMT Reply #417 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/417#message417 http://yam.ch/discussion/message/417#message417 <blockquote class="citation"> <p> I checked your permissions and tuned the trac permissions accordingly. Please check again. Now you should be able to renamed and even delete pages as you like. </p> </blockquote> <p> Thanks ! I'm going to rename the ARexx pages. </p> Message damato Mon, 21 Oct 2013 23:07:54 GMT Reply #416 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/416#message416 http://yam.ch/discussion/message/416#message416 <blockquote class="citation"> <blockquote class="citation"> <blockquote class="citation"> <p> Can I use the "revision" (negative value) and "outdated" comment on main pages ? For example, I'd like to highlight the fact that the newer rx_findmail needs to be updated. (Well, I'll test this.) </p> </blockquote> <p> I think that should be possible. </p> </blockquote> <p> Adding a "revision" to the main pages produce an error as shown by the ShowProblem. </p> </blockquote> <p> Yes, you are right. So the english pages shouldn't contain any TranslatedPages macro with the revision option. However, using the "outdated" option should be no problem. </p> <blockquote class="citation"> <blockquote class="citation"> <blockquote class="citation"> <p> A single TOC call for the content of the current page, or the global one as seen on "User license". Isn't the global one a bit invasive to have it on all pages ? </p> </blockquote> <p> I think there are also some addition options for the TOC macro that should help to tune it so that it isn't that much invasive. See, for example, the call I added to the <a class="missing wiki">Documentation/ARexx API?</a> page. I limited it to the "ARexx <acronym title="Application Program Interface">API</acronym>" domain part of the online Documentation. </p> </blockquote> <p> Is there a way to get rid of the "Documentation" and "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/" parts in the TOC ? </p> </blockquote> <p> I haven't found one yet. However, I will have a look if that's possible and if not tune the macro to allow this as it would really be helpful. </p> <blockquote class="citation"> <blockquote class="citation"> <p> First of all, the wiki pages are no files somewhere but simply database entries in the trac system. So renaming them is just a matter of changing a reference. So all you have to do is using the "Rename page" link at the bottom of each page and then rename it accordingly. The only thing that is partly annoying is that you then afterwards have to search for orphaned references throughout the wiki. However, this could easily be done by using the search functionality of trac at the top right corner of each page. In fact, I just did this as an example for the ADDRDELETE page. Please have a look. </p> </blockquote> <p> Ha ok, I better understand now. </p> <p> However, I don't have such a possibility as to "Rename page". All I have is: </p> <blockquote> <p> <tt>Edit this page</tt> <tt>Attach file</tt> </p> </blockquote> <p> and while in edition mode: </p> <blockquote> <p> <tt>Preview Page</tt> <tt>Review Changes</tt> <tt>Submit changes</tt> <tt>Cancel</tt> </p> </blockquote> </blockquote> <p> Ok, I see. I checked your permissions and tuned the trac permissions accordingly. Please check again. Now you should be able to renamed and even delete pages as you like. </p> Message AmigaPhil Mon, 21 Oct 2013 19:00:05 GMT Reply #415 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/415#message415 http://yam.ch/discussion/message/415#message415 <blockquote class="citation"> <blockquote class="citation"> <p> Can I use the "revision" (negative value) and "outdated" comment on main pages ? For example, I'd like to highlight the fact that the newer rx_findmail needs to be updated. (Well, I'll test this.) </p> </blockquote> <p> I think that should be possible. </p> </blockquote> <p> Adding a "revision" to the main pages produce an error as shown by the ShowProblem. </p> <blockquote class="citation"> <blockquote class="citation"> <p> A single TOC call for the content of the current page, or the global one as seen on "User license". Isn't the global one a bit invasive to have it on all pages ? </p> </blockquote> <p> I think there are also some addition options for the TOC macro that should help to tune it so that it isn't that much invasive. See, for example, the call I added to the <a class="missing wiki">Documentation/ARexx API?</a> page. I limited it to the "ARexx <acronym title="Application Program Interface">API</acronym>" domain part of the online Documentation. </p> </blockquote> <p> Is there a way to get rid of the "Documentation" and "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/" parts in the TOC ? </p> <blockquote class="citation"> <p> First of all, the wiki pages are no files somewhere but simply database entries in the trac system. So renaming them is just a matter of changing a reference. So all you have to do is using the "Rename page" link at the bottom of each page and then rename it accordingly. The only thing that is partly annoying is that you then afterwards have to search for orphaned references throughout the wiki. However, this could easily be done by using the search functionality of trac at the top right corner of each page. In fact, I just did this as an example for the ADDRDELETE page. Please have a look. </p> </blockquote> <p> Ha ok, I better understand now. </p> <p> However, I don't have such a possibility as to "Rename page". All I have is: </p> <blockquote> <p> <tt>Edit this page</tt> <tt>Attach file</tt> </p> </blockquote> <p> and while in edition mode: </p> <blockquote> <p> <tt>Preview Page</tt> <tt>Review Changes</tt> <tt>Submit changes</tt> <tt>Cancel</tt> </p> </blockquote> Message damato Sun, 20 Oct 2013 21:49:07 GMT Reply #414 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/414#message414 http://yam.ch/discussion/message/414#message414 <blockquote class="citation"> <p> Ok, I'll look at that. If I've understood it right, the "revision" argument is only for translated pages, so that that revision number can be compared to the main (English) page version. </p> </blockquote> <p> Exactly. </p> <blockquote class="citation"> <p> Can I use the "revision" (negative value) and "outdated" comment on main pages ? For example, I'd like to highlight the fact that the newer rx_findmail needs to be updated. (Well, I'll test this.) </p> </blockquote> <p> I think that should be possible. </p> <blockquote class="citation"> <blockquote class="citation"> <p> Furthermore, I do have the following comments regarding the online docu: </p> <ol><li>Please make sure to always add TOC macro usage on all pages so that nagivating is more easy. </li></ol></blockquote> <p> A single TOC call for the content of the current page, or the global one as seen on "User license". Isn't the global one a bit invasive to have it on all pages ? </p> </blockquote> <p> I think there are also some addition options for the TOC macro that should help to tune it so that it isn't that much invasive. See, for example, the call I added to the <a class="missing wiki">Documentation/ARexx API?</a> page. I limited it to the "ARexx <acronym title="Application Program Interface">API</acronym>" domain part of the online Documentation. </p> <blockquote class="citation"> <blockquote class="citation"> <ol start="2"><li>Please rename the "rexl" and "rexx" pages to be more consistent with the other page names (Uppercase letter start and more descriptive name) </li></ol></blockquote> <p> You are right. I realized that afterward when I saw it was not really verbose in the TOC. How about "ARexx by function" and "ARexx list" ? </p> <p> But... (see below) </p> </blockquote> <p> I just renamed them here to "ARexx <acronym title="Application Program Interface">API</acronym>/List by Function" and "ARexx <acronym title="Application Program Interface">API</acronym>/List by Name". </p> <blockquote class="citation"> <blockquote class="citation"> <ol start="3"><li>Please move all the "rx_XXXXX" pages under "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/XXXXX" with the arexx command name in uppercase letters so that you will end up with "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/ADDRDELETE" or something like that. </li></ol></blockquote> <p> Yes, that's a good idea. But isn't it too late now ? </p> <p> Beside other long (borring) copy/paste sessions, that will also leave around 150 orphean files on the wiki (English + Spanish Arexx docs). Is there a way to delete those files ? Or even better, a wiki/php or something else command/macro to move files ? </p> </blockquote> <p> First of all, the wiki pages are no files somewhere but simply database entries in the trac system. So renaming them is just a matter of changing a reference. So all you have to do is using the "Rename page" link at the bottom of each page and then rename it accordingly. The only thing that is partly annoying is that you then afterwards have to search for orphaned references throughout the wiki. However, this could easily be done by using the search functionality of trac at the top right corner of each page. In fact, I just did this as an example for the ADDRDELETE page. Please have a look. </p> Message AmigaPhil Sun, 20 Oct 2013 19:19:52 GMT Reply #413 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/413#message413 http://yam.ch/discussion/message/413#message413 <blockquote class="citation"> <p> Please note, that there are certain features of the TranslatedPages macro you should be aware of. So please check its documentation at <a class="ext-link" href="http://trac-hacks.org/wiki/TranslatedPagesMacro"><span class="icon">​</span>http://trac-hacks.org/wiki/TranslatedPagesMacro</a> </p> <p> The most important feature is the "revision=XXX" and "outdated=XXXX" options you can supply to it. By consitently using it in all pages/calls of the TranslatedPages macro you make it more easy to identify the differences compared to the base language (english). Please note my changes to the <a class="wiki" href="/wiki/Localization">Localization</a> wiki page where I added two TranslatedPages calls with showproblems and showstatus arguments. I think you will immediately understand how helpful the addition of the "revision=" and "outdated=" options are. So please make use of it so that future changes to the base english version will immediatley be visible in the other translations. </p> </blockquote> <p> Ok, I'll look at that. If I've understood it right, the "revision" argument is only for translated pages, so that that revision number can be compared to the main (English) page version. </p> <p> Can I use the "revision" (negative value) and "outdated" comment on main pages ? For example, I'd like to highlight the fact that the newer rx_findmail needs to be updated. (Well, I'll test this.) </p> <blockquote class="citation"> <p> Furthermore, I do have the following comments regarding the online docu: </p> <ol><li>Please make sure to always add TOC macro usage on all pages so that nagivating is more easy. </li></ol></blockquote> <p> A single TOC call for the content of the current page, or the global one as seen on "User license". Isn't the global one a bit invasive to have it on all pages ? </p> <blockquote class="citation"> <ol start="2"><li>Please rename the "rexl" and "rexx" pages to be more consistent with the other page names (Uppercase letter start and more descriptive name) </li></ol></blockquote> <p> You are right. I realized that afterward when I saw it was not really verbose in the TOC. How about "ARexx by function" and "ARexx list" ? </p> <p> But... (see below) </p> <blockquote class="citation"> <ol start="3"><li>Please move all the "rx_XXXXX" pages under "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/XXXXX" with the arexx command name in uppercase letters so that you will end up with "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/ADDRDELETE" or something like that. </li></ol></blockquote> <p> Yes, that's a good idea. But isn't it too late now ? </p> <p> Beside other long (borring) copy/paste sessions, that will also leave around 150 orphean files on the wiki (English + Spanish Arexx docs). Is there a way to delete those files ? Or even better, a wiki/php or something else command/macro to move files ? </p> Message damato Sat, 19 Oct 2013 22:10:37 GMT Reply #412 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/412#message412 http://yam.ch/discussion/message/412#message412 <p> Hi, </p> <p> let me first thank you again for your hard work. We really appreciate it that the YAM documentation seems to be in good hand again and that it is going to be improved step-by-step. </p> <blockquote class="citation"> <p> I've (almost) finished with the English documentation. As these "new" pages will be used as a base for translations to other languages, could you please review them to check if they are complete and up-to-date ? (And for dead links if any.) </p> </blockquote> <p> I have quickly looked over it and I think they pretty much replicate now what the original amigaguide documents provided regarding documentation. So I feel they could really serve as a good starting point. I haven't checked all links now and verified the content of all pages, but when I will have more time reading through it I will try to improve things accordingly. </p> <p> Please note, that there are certain features of the TranslatedPages macro you should be aware of. So please check its documentation at <a class="ext-link" href="http://trac-hacks.org/wiki/TranslatedPagesMacro"><span class="icon">​</span>http://trac-hacks.org/wiki/TranslatedPagesMacro</a> </p> <p> The most important feature is the "revision=XXX" and "outdated=XXXX" options you can supply to it. By consitently using it in all pages/calls of the TranslatedPages macro you make it more easy to identify the differences compared to the base language (english). Please note my changes to the <a class="wiki" href="/wiki/Localization">Localization</a> wiki page where I added two TranslatedPages calls with showproblems and showstatus arguments. I think you will immediately understand how helpful the addition of the "revision=" and "outdated=" options are. So please make use of it so that future changes to the base english version will immediatley be visible in the other translations. </p> <p> Furthermore, I do have the following comments regarding the online docu: </p> <ol><li>Please make sure to always add TOC macro usage on all pages so that nagivating is more easy. </li><li>Please rename the "rexl" and "rexx" pages to be more consistent with the other page names (Uppercase letter start and more descriptive name) </li><li>Please move all the "rx_XXXXX" pages under "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/XXXXX" with the arexx command name in uppercase letters so that you will end up with "Documentation/ARexx <acronym title="Application Program Interface">API</acronym>/ADDRDELETE" or something like that. </li></ol><blockquote class="citation"> <p> I have not added the credits page. Should it be created in the documentation section (Eg. bottom of the main documentation page ?) or somewhere else on the wiki ? </p> </blockquote> <p> Well, again it is up to you. But I would say put it in the documentation section. If we need it as a general wiki page we can link from there to the documentation. </p> Message AmigaPhil Tue, 15 Oct 2013 18:28:43 GMT Reply #411 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/411#message411 http://yam.ch/discussion/message/411#message411 <p> I've (almost) finished with the English documentation. As these "new" pages will be used as a base for translations to other languages, could you please review them to check if they are complete and up-to-date ? (And for dead links if any.) </p> <p> I have not added the credits page. Should it be created in the documentation section (Eg. bottom of the main documentation page ?) or somewhere else on the wiki ? </p> Message AmigaPhil Fri, 04 Oct 2013 20:15:43 GMT Reply #410 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/410#message410 http://yam.ch/discussion/message/410#message410 <blockquote class="citation"> <p> I don't think so. You have to place the TranslatedPages macro before/above the TOC macro which will in the end then show up two yellow boxes to choose. And I think this is the only correct way. </p> </blockquote> <p> Adding a Line Feed ("\\") between the 2 macros does the trick. Text is now also wrapping around the second macro area. </p> Message damato Fri, 04 Oct 2013 19:47:52 GMT Reply #409 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/409#message409 http://yam.ch/discussion/message/409#message409 <blockquote class="citation"> <p> Is the "Getting help" section on the main documentation page still worth it ? </p> <p> The "Known problems" part from the AmigaGuide is outdated, and most of the problems are already addressed. And the "Support" link is a bit obsolete as there are links to the <acronym title="Frequently Asked Questions">FAQ</acronym>, forums, and bug tracking later on the same page. </p> <p> How about to remove it ? </p> </blockquote> <p> Well, to be honest. I dunno. When I started the online documentation here I simply started to mimick the original layout of the amigaguide document. However, with the online documentation we do have so much more possibilities I guess there are hundreds of areas where we can approve the documentation. </p> <p> So, <acronym title="In my humble opinion...">IMHO</acronym> you are the documentation maintainer now and as such feel free to modify whatever you feel should be added or removed. We really trust you in this respect and really appreciate your efforts! So please don't simply copy over all information from the amigaguide documents, but don't stop there and continue to improve/enhance the documentation as you see fit. </p> Message damato Fri, 04 Oct 2013 19:43:58 GMT Reply #408 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/408#message408 http://yam.ch/discussion/message/408#message408 <blockquote class="citation"> <p> Done with the Spanish translations for ARexx as well. </p> <p> I tried to add the TranslatedPages macro to the "What is e-mail" pages, but then, the text is wrapped around the TranslatedPages area, but not anymore around the TOC area. Can the two macros areas be merged as a single area ? </p> </blockquote> <p> I don't think so. You have to place the TranslatedPages macro before/above the TOC macro which will in the end then show up two yellow boxes to choose. And I think this is the only correct way. </p> Message AmigaPhil Fri, 04 Oct 2013 19:03:20 GMT Reply #407 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/407#message407 http://yam.ch/discussion/message/407#message407 <p> Is the "Getting help" section on the main documentation page still worth it ? </p> <p> The "Known problems" part from the AmigaGuide is outdated, and most of the problems are already addressed. And the "Support" link is a bit obsolete as there are links to the <acronym title="Frequently Asked Questions">FAQ</acronym>, forums, and bug tracking later on the same page. </p> <p> How about to remove it ? </p> Message AmigaPhil Thu, 03 Oct 2013 19:09:21 GMT Reply #406 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/406#message406 http://yam.ch/discussion/message/406#message406 <p> Done with the Spanish translations for ARexx as well. </p> <p> I tried to add the TranslatedPages macro to the "What is e-mail" pages, but then, the text is wrapped around the TranslatedPages area, but not anymore around the TOC area. Can the two macros areas be merged as a single area ? </p> Message AmigaPhil Tue, 01 Oct 2013 20:45:33 GMT Reply #405 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/405#message405 http://yam.ch/discussion/message/405#message405 <p> Great ! </p> <p> I stop for today. I'll add the macro link later. </p> Message damato Tue, 01 Oct 2013 20:41:02 GMT Reply #404 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/404#message404 http://yam.ch/discussion/message/404#message404 <blockquote class="citation"> <p> The macro will work on every pages, really ? It's a kind of magic. <img src="/chrome/emoticons/smile.png" alt=":-)" class="emoticon" width="18" height="18" style="vertical-align: middle" /> </p> </blockquote> <p> Yes, it will work on every page, that's why you should use it. </p> <blockquote class="citation"> <p> What if a similar page on another language does not exist, will the macro fall back to the English doc ? </p> </blockquote> <p> I don't think so. AFAIR it will just show an error. However as soon as I am back from vacation, i'll bug Dirk Stöcker about that since he is the maintainer of that macro and thus could eadily tune it to behave like that. </p> <blockquote class="citation"> <p> And from Yam ? Will an Italian user clicking on the help menu see the English main document or an empty page ? </p> </blockquote> <p> When we tube the yam sources and the macro accordingly, an italian user will immediately see the italian translation, and if it doesn't exist it will fallback to the english page. </p> Message AmigaPhil Tue, 01 Oct 2013 20:33:02 GMT Reply #403 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/403#message403 http://yam.ch/discussion/message/403#message403 <p> The macro will work on every pages, really ? It's a kind of magic. <img src="/chrome/emoticons/smile.png" alt=":-)" class="emoticon" width="18" height="18" style="vertical-align: middle" /> </p> <p> What if a similar page on another language does not exist, will the macro fall back to the English doc ? </p> <p> And from Yam ? Will an Italian user clicking on the help menu see the English main document or an empty page ? </p> Message damato Tue, 01 Oct 2013 20:15:36 GMT Reply #402 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/402#message402 http://yam.ch/discussion/message/402#message402 <p> Ok perfect. I can see that you already started. Very nice! However, please make sure that every documentation page starts with the [TranslatedPages] macro so that people can easily switch between translations on every documentation page. Currently only the main documentation pages use thst macro. But it would be better if any documentazion page is using it! </p> <p> Jens </p> Message AmigaPhil Mon, 30 Sep 2013 14:18:21 GMT Reply #401 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/401#message401 http://yam.ch/discussion/message/401#message401 <p> Ok. </p> <p> As the Spanish translation for the ARexx documentation seems complete, I'll start with that, then going on with the English doc. </p> Message damato Sun, 29 Sep 2013 19:18:38 GMT Reply #400 to topic #109 - Online documentation and wiki formatting http://yam.ch/discussion/message/400#message400 http://yam.ch/discussion/message/400#message400 <blockquote class="citation"> <p> I don't understand how to create and edit the "post-it" on wiki pages. It looks like a include instruction, but I don't find where to edit the contents. </p> <p> For example, I tried to add 2 more languages (Français and Español) on the Languages "post-it" of the main documentation page, but when editing that page, I only see a "[[TranslatedPages]]" link and can't find that TranslatedPages document. </p> </blockquote> <p> I guess with the 'post-it' you mean the yellow area currently showing Deutsch and English only. </p> <p> As you already guessed correctly, this particular box is automatically generated. In fact, the "[TranslatedPages] statement refers to a trac plugin I installed a while ago. See here for more information ob that macro: <a class="ext-link" href="http://trac-hacks.org/wiki/TranslatedPagesMacro"><span class="icon">​</span>http://trac-hacks.org/wiki/TranslatedPagesMacro</a> </p> <p> The point behind that macro is that, you simply have to generate a copy of a wiki page like the 'Documentation' main page, but name it 'de:Documentation'. Then the TranslatedPages macro will identify that there is a german translation for that page and thus will automatically present this yellow box with the existing translations. </p> <p> If we would thus follow that procedure for every documentation related wiki pages we could then also automatically redirect people to the right translation based on their used catalog/language in YAM if they press the HELP key. </p> <p> So please, feel free to work on internationalization of the online documentation as far as possible. We really appreciate your work regarding the online docu and we would be happy to credit you in the about window of YAM if you continue to tune it! So feel free to edit whatever you want regarding the online docu and consider youself the maintainer of it now <img src="/chrome/emoticons/wink.png" alt=";)" class="emoticon" width="18" height="18" style="vertical-align: middle" /> </p> <p> Best regards Jens </p> Message