From: Thijs K. <ki...@sq...> - 2005-05-23 09:50:04
|
Hey people, Contained in the squirrelmail is a doc/ dir with some seemingly random bits of documentation. This is both end-user (admin) documentation aswell as background info for developers. It would be good if at least the documentation for the end-user/admin would be expanded / integrated or otherwise improved into a SquirrelMail User Manual with different chapters. This is probably a slow, gradual process, but the first thing we need is to separate out the devel info. That's what I'm going to do somewhere in the upcoming days: move those documents to a 'development' subdir of doc/ This would look like: doc/: README.russian_apache authentication.txt db-backend.txt i18n.txt ie_ssl.txt presets.txt themes.txt translating.txt translating_help.txt doc/development/: addressbook.txt compose.txt mime.txt plugin.txt rfc_documents.txt tree.txt doc/ReleaseNotes/: the release notes Any objections, ideas or comments, please let me know. I will be committing this sometime soon. Regards, Thijs |
From: Tomas K. <to...@us...> - 2005-05-23 10:20:55
|
> Hey people, > > Contained in the squirrelmail is a doc/ dir with some seemingly random > bits of documentation. This is both end-user (admin) documentation aswell > as background info for developers. > > It would be good if at least the documentation for the end-user/admin > would be expanded / integrated or otherwise improved into a SquirrelMail > User Manual with different chapters. This is probably a slow, gradual > process, but the first thing we need is to separate out the devel info. > That's what I'm going to do somewhere in the upcoming days: move those > documents to a 'development' subdir of doc/ > > This would look like: > > doc/: > README.russian_apache > authentication.txt > db-backend.txt > i18n.txt > ie_ssl.txt > presets.txt > themes.txt > translating.txt > translating_help.txt > > doc/development/: > addressbook.txt > compose.txt > mime.txt > plugin.txt > rfc_documents.txt > tree.txt > > doc/ReleaseNotes/: > the release notes > > > Any objections, ideas or comments, please let me know. I will be > committing this sometime soon. one idea. create sgml formated user manual, move some bits of information from wiki into it and use it on squirrelmail site instead of wiki. or next to wiki. It might save us some sql connections. sgml allows to generate html, text, pdf and other formats from single file. Example: http://smstats.topolis.lt/docs/trans-ref.html -- Tomas |
From: Thijs K. <ki...@sq...> - 2005-05-23 10:34:42
|
> create sgml formated user manual, move some bits of information from wiki > into it and use it on squirrelmail site instead of wiki. or next to > wiki. It might save us some sql connections. Sure, a great plan. We could use a general user manual that details installation, configuration, optimizing performance, plugins, special tasks like db-backend etc. Once the devel docs are out of the way, we could make an outline of this document (in swql) with the main chapters, under the doc/ dir. Then everyone could contribute in the area's that they feel competent enough about. The end result can then be exported also to the website. regards Thijs |
From: Jonathan A. <jo...@sq...> - 2005-05-24 19:52:27
|
Hello Thijs Kinkhorst, On Monday, May 23, 2005, you wrote: > Hey people, > Contained in the squirrelmail is a doc/ dir with some seemingly random > bits of documentation. This is both end-user (admin) documentation aswell > as background info for developers. While in general, I agree with the shuffling of the docs to a better structure, giving the admins some time to respond before going off and doing it would have been a lot nicer! -- Jonathan Angliss <jo...@sq...> |
From: Thijs K. <ki...@sq...> - 2005-05-25 08:37:34
|
On Tue, May 24, 2005 21:52, Jonathan Angliss wrote: > While in general, I agree with the shuffling of the docs to a better > structure, giving the admins some time to respond before going off and > doing it would have been a lot nicer! Sure, but it's a rather minor change, and it was expected not to cause much trouble or concern. That's why I thought I struck the right balance here: a quick question if it was ok, just to be sure, but not more than that. Since I received some confirmation and no immediate objections, also after asking the same question on IRC, I didn't see the need to wait longer with this. It is after all not a really significant thing. I'm sorry if you also wanted to comment on it, I do value your opinion, but we should keep a distinction between significant and less-significant changes where the latter do not need everyone to express their explicit approval IMO. regards Thijs |
From: Tomas K. <to...@us...> - 2005-05-25 18:15:20
|
>> create sgml formated user manual, move some bits of information from >> wiki >> into it and use it on squirrelmail site instead of wiki. or next to >> wiki. It might save us some sql connections. > > Sure, a great plan. We could use a general user manual that details > installation, configuration, optimizing performance, plugins, special > tasks like db-backend etc. Once the devel docs are out of the way, we > could make an outline of this document (in swql) with the main chapters, > under the doc/ dir. Then everyone could contribute in the area's that they > feel competent enough about. The end result can then be exported also to > the website. http://www.topolis.lt/docs/manual/ http://www.topolis.lt/docs/manual/index2.html only makefile, manual.sgml and index2.html files are not generated. We can have user and install manuals separated. I am thinking about adding those three files to squirrelmail/doc/manual/ in devel cvs. http://www.topolis.lt/docs/sgml/ directory contains two sgml manuals. -- Tomas |
From: Jonathan A. <jo...@sq...> - 2005-05-25 19:05:46
|
Hello Tomas Kuliavas, On Wednesday, May 25, 2005, you wrote: >>> create sgml formated user manual, move some bits of information >>> from wiki into it and use it on squirrelmail site instead of wiki. >>> or next to wiki. It might save us some sql connections. >> Sure, a great plan. We could use a general user manual that details >> installation, configuration, optimizing performance, plugins, special >> tasks like db-backend etc. Once the devel docs are out of the way, we >> could make an outline of this document (in swql) with the main chapters, >> under the doc/ dir. Then everyone could contribute in the area's that they >> feel competent enough about. The end result can then be exported also to >> the website. > http://www.topolis.lt/docs/manual/ > http://www.topolis.lt/docs/manual/index2.html > only makefile, manual.sgml and index2.html files are not generated. We can > have user and install manuals separated. I like it... "Looks" great. > I am thinking about adding those three files to squirrelmail/doc/manual/ > in devel cvs. Sounds good to me. Do we want to break it down to three manuals? Dev, User, Admin? Dev for development stuff (plugins, coders, etc), user for... well... users, and admin for stuff like install, deployment, etc etc. -- Jonathan Angliss <jo...@sq...> |
From: Thijs K. <ki...@sq...> - 2005-05-26 08:24:46
|
On Wed, May 25, 2005 21:05, Jonathan Angliss wrote: > Do we want to break it down to three manuals? Dev, User, Admin? Dev > for development stuff (plugins, coders, etc), user for... well... users, > and admin for stuff like install, deployment, etc etc. I think this is the right way to go. I'd start with the Admin documentation, since I feel that that is mostly lacking now. While we have quite some bits of information lying around in the tarball and on our site, we need to combine that in a comprehensive document. For this I can think up the following chapters: - Quick start guide - Full installation - Upgrading - Configuration - basic - IMAP server type and parameters - authentication - db-backends - optimizing performance - other configuration issues - internationalisation - plugins and themes - FAQ for assorted questions not answered elsewhere - where to get support, and how to report bugs, feature requests and patches Any additions to this? If we agree on some a layout for this then maybe Tomas can set that up in CVS as a starting point. Then everyone who wants to can contribute on specific sections. Thijs |
From: Jonathan A. <jo...@sq...> - 2005-05-26 21:27:19
|
Hello Thijs Kinkhorst, On Thursday, May 26, 2005, you wrote: >> Do we want to break it down to three manuals? Dev, User, Admin? Dev >> for development stuff (plugins, coders, etc), user for... well... >> users, and admin for stuff like install, deployment, etc etc. > I think this is the right way to go. I'd start with the Admin > documentation, since I feel that that is mostly lacking now. Generally agreed ;) I think our documentation is lacking all over the place. > While we have quite some bits of information lying around in the > tarball and on our site, we need to combine that in a comprehensive > document. Agreed. > For this I can think up the following chapters: > - Quick start guide > - Full installation > - Upgrading > - Configuration > - basic > - IMAP server type and parameters > - authentication > - db-backends > - optimizing performance > - other configuration issues > - internationalisation > - plugins and themes > - FAQ for assorted questions not answered elsewhere > - where to get support, and how to report bugs, > feature requests and patches > Any additions to this? Those look good for our first attempt. I dare say while going through, we'll probably come up with quite a few others. > If we agree on some a layout for this then maybe Tomas can set that > up in CVS as a starting point. Then everyone who wants to can > contribute on specific sections. We might want to start a whole new branch (documentation?) for just this and keep it out of the code. That way devel and stable branches don't have to be updated for all changes. Plus it'd make it easier to work on having a team "dedicated" to documentation, and controlling permissions and all that fun stuff, not that is an issue at the moment. -- Jonathan Angliss <jo...@sq...> |
From: Tomas K. <to...@us...> - 2005-05-27 08:33:57
|
> Hello Thijs Kinkhorst, > On Thursday, May 26, 2005, you wrote: > >>> Do we want to break it down to three manuals? Dev, User, Admin? Dev >>> for development stuff (plugins, coders, etc), user for... well... >>> users, and admin for stuff like install, deployment, etc etc. > >> I think this is the right way to go. I'd start with the Admin >> documentation, since I feel that that is mostly lacking now. > > Generally agreed ;) I think our documentation is lacking all over the > place. > >> While we have quite some bits of information lying around in the >> tarball and on our site, we need to combine that in a comprehensive >> document. > > Agreed. > >> For this I can think up the following chapters: > >> - Quick start guide >> - Full installation >> - Upgrading >> - Configuration >> - basic >> - IMAP server type and parameters >> - authentication >> - db-backends >> - optimizing performance >> - other configuration issues >> - internationalisation >> - plugins and themes >> - FAQ for assorted questions not answered elsewhere >> - where to get support, and how to report bugs, >> feature requests and patches > > >> Any additions to this? > > Those look good for our first attempt. I dare say while going > through, we'll probably come up with quite a few others. sections are created in admin.sgml. >> If we agree on some a layout for this then maybe Tomas can set that >> up in CVS as a starting point. Then everyone who wants to can >> contribute on specific sections. > > We might want to start a whole new branch (documentation?) for just > this and keep it out of the code. That way devel and stable branches > don't have to be updated for all changes. Plus it'd make it easier to > work on having a team "dedicated" to documentation, and controlling > permissions and all that fun stuff, not that is an issue at the > moment. we can create new cvs module named docs and move files from squirrelmail/doc/manual to docs/manual. It can also hold phpdoc files from squirrelmail/contrib. -- Tomas |
From: Jonathan A. <jo...@sq...> - 2005-05-27 14:07:11
|
Hello Tomas Kuliavas, On Friday, May 27, 2005, you wrote: >>> For this I can think up the following chapters: >> >>> - Quick start guide >>> - Full installation >>> - Upgrading >>> - Configuration >>> - basic >>> - IMAP server type and parameters >>> - authentication >>> - db-backends >>> - optimizing performance >>> - other configuration issues >>> - internationalisation >>> - plugins and themes >>> - FAQ for assorted questions not answered elsewhere >>> - where to get support, and how to report bugs, >>> feature requests and patches >> >> >>> Any additions to this? >> >> Those look good for our first attempt. I dare say while going >> through, we'll probably come up with quite a few others. > sections are created in admin.sgml. Great start... thank you :) >>> If we agree on some a layout for this then maybe Tomas can set that >>> up in CVS as a starting point. Then everyone who wants to can >>> contribute on specific sections. >> >> We might want to start a whole new branch (documentation?) for just >> this and keep it out of the code. That way devel and stable branches >> don't have to be updated for all changes. Plus it'd make it easier to >> work on having a team "dedicated" to documentation, and controlling >> permissions and all that fun stuff, not that is an issue at the >> moment. > we can create new cvs module named docs and move files from > squirrelmail/doc/manual to docs/manual. It can also hold phpdoc files from > squirrelmail/contrib. That sounds like a good plan. -- Jonathan Angliss <jo...@sq...> |
From: Jonathan A. <jo...@sq...> - 2005-05-27 14:17:13
|
Hello Tomas Kuliavas, On Friday, May 27, 2005, you wrote: >> Hello Thijs Kinkhorst, >> On Thursday, May 26, 2005, you wrote: >> >>>> Do we want to break it down to three manuals? Dev, User, Admin? Dev >>>> for development stuff (plugins, coders, etc), user for... well... >>>> users, and admin for stuff like install, deployment, etc etc. >> >>> I think this is the right way to go. I'd start with the Admin >>> documentation, since I feel that that is mostly lacking now. >> >> Generally agreed ;) I think our documentation is lacking all over the >> place. >> >>> While we have quite some bits of information lying around in the >>> tarball and on our site, we need to combine that in a comprehensive >>> document. >> >> Agreed. >> >>> For this I can think up the following chapters: >> >>> - Quick start guide >>> - Full installation >>> - Upgrading >>> - Configuration >>> - basic >>> - IMAP server type and parameters >>> - authentication >>> - db-backends >>> - optimizing performance >>> - other configuration issues >>> - internationalisation >>> - plugins and themes >>> - FAQ for assorted questions not answered elsewhere >>> - where to get support, and how to report bugs, >>> feature requests and patches >> >> >>> Any additions to this? >> >> Those look good for our first attempt. I dare say while going >> through, we'll probably come up with quite a few others. > sections are created in admin.sgml. >>> If we agree on some a layout for this then maybe Tomas can set that >>> up in CVS as a starting point. Then everyone who wants to can >>> contribute on specific sections. >> >> We might want to start a whole new branch (documentation?) for just >> this and keep it out of the code. That way devel and stable branches >> don't have to be updated for all changes. Plus it'd make it easier to >> work on having a team "dedicated" to documentation, and controlling >> permissions and all that fun stuff, not that is an issue at the >> moment. > we can create new cvs module named docs and move files from > squirrelmail/doc/manual to docs/manual. It can also hold phpdoc files from > squirrelmail/contrib. Hrm, looks like you've already committed stuff, but not as a new module, just a sub-directory of the docs/ folder. I was thinking a new module would be better to save updates across both branches... valcor@titan tmp $ cvs -d:ext:jan...@cv...:/cvsroot/squirrelmail co docs cvs server: cannot find module `docs' - ignored cvs [checkout aborted]: cannot expand modules valcor@titan tmp $ cvs -d:ext:jan...@cv...:/cvsroot/squirrelmail co doc cvs server: cannot find module `doc' - ignored cvs [checkout aborted]: cannot expand modules Unless I did something wrong? :) -- Jonathan Angliss <jo...@sq...> |
From: Chris H. <ta...@sq...> - 2005-05-27 14:11:07
|
> sections are created in admin.sgml. I looked over the docs yesterday. While I'm not fluent in SGML, is there any reason we're going to use Article rather than Book? From my skimming of the SGML docs, Book seems much less..er..stripped down. --=20 Chris Hilts ta...@sq... |
From: Tomas K. <to...@us...> - 2005-05-27 15:14:20
|
>> sections are created in admin.sgml. > > I looked over the docs yesterday. While I'm not fluent in SGML, is there > any reason we're going to use Article rather than Book? From my skimming > of the SGML docs, Book seems much less..er..stripped down. it was used in linuxdoc-tools example and guide documentation. It is only a start of documentation that could free some DB connections on sourceforge. You are free to use other format or make it better. sgml files are added to documentation module. export CVSROOT=":ext:use...@cv...:/cvsroot/squirrelmail" cvs co documentation will add Makefile and other scripts later. -- Tomas |