gmane.comp.horde.devel

Re: Fancy Horde/Imap_Client documentation

Jan Schneider — 2013-06-18T20:19:34

Zitat von Michael M Slusarz <slusarz< at >horde.org>:


Maybe I wasn't clear. I consider the wiki to be the source of the  
documentation, and doing what it does best: allowing easy editing and  
formatting of text. The location where we should point people to, is  
the website. The library section is just a start there and could  
definitely use some more love, but it's much better than maintaining  
yet another website.

So this is the workflow:
1) Editing in the wiki: http://wiki.horde.org/Doc/Dev/HordeArgv
2) Converting to reST:  
http://wiki.horde.org/Doc/Dev/HordeArgv?actionID=export&format=rst
3) Bundling with PEAR package:  
http://git.horde.org/horde-git/-/browse/framework/Argv/doc/Horde/Argv/
4) Building for website: http://www.horde.org/libraries/Horde_Argv/docs/README

Steps 2-4 are supported by horde-component.

Re: Fancy Horde/Imap_Client documentation

Michael M Slusarz — 2013-06-18T18:26:20

Quoting Michael J Rubinsky <mrubinsk< at >horde.org>:


For the record... this is exclusively what I use also.  But I  
guarantee we are in the minority - it does take quite a bit of prior  
Horde/PHP knowledge to understand things like file layouts to be able  
to do this.


This last 2-3 are probably the most important.  Right now, the  
documentation is trying to be geared to those people who want an  
alternative to imap's c-client library.  That's what I want to tailor  
the examples to.  I am thinking it might be useful to do some sort of  
mapping from c-client methods -> Imap_Client functionality.

The CONDSTORE/QRESYNC stuff is also what I am very interested in also  
- since we truly are the only solution that provides this.  So it's a  
balancing act of trying to get people to dip their toes into using the  
library vs. informing these people -- and letting the more advanced  
people know -- that our software can handle this also.

michael

___________________________________
Michael Slusarz [slusarz< at >h

Re: Fancy Horde/Imap_Client documentation

Michael M Slusarz — 2013-06-18T18:21:43

Quoting Jan Schneider <jan< at >horde.org>:


Right now I have to manually convert all the code to formatting (by  
putting in SPAN classes - ugh).  I really need either an automated way  
of doing this (I'd rather not have a javascript solution) or some  
location where I can insert the code and then copy/paste the HTML  
source.  That's really what was preventing me from providing other  
examples.


Unfortunately, I'm going to have to disagree with you.

As someone who has used the Horde_Argv documentation on the wiki, it  
*was* useful in terms of figuring out some of the details.  But there  
is NO way the Horde_Argv documentation, as presented on our wiki,  
would ever convince me to use that library over some other competing  
library.  Horde_Argv may be the most professional, bug-free,  
comprehensive argument parsing library out there.  But I would never  
know that from the documentation.  This is a limitation of using a  
wiki as the main page.

What I am trying to address is concerns I have heard from

Re: Imp and Horde_Stream_Filter

Michael M Slusarz — 2013-06-18T17:46:51

Quoting Remi Collet <remi< at >fedoraproject.org>:


Required.  Fixed for 6.1.3.

michael

___________________________________
Michael Slusarz [slusarz< at >horde.org]

Imp and Horde_Stream_Filter

Remi Collet — 2013-06-18T16:40:54

From package.xml

Horde_Stream_Filter is list twice.

in the "required" dependencies
in the "optional" dependencies

So, is it required or optional ?  ;)


Remi.

Re: Git splitting

Ralf Lang — 2013-06-20T07:20:41

Am 20.06.2013 09:15, schrieb Thomas Jarosch:

Only if you need everything and all. Most contributions apart from main
developers are patches to single libraries or apps. Often they are
developed against stable releases and only ported to the git versions.

On the other hand, if you want to actually _run_ git checkouts, you need
some understanding of what requires what (if no metadata/script handles
that for you).

Re: Git splitting

Thomas Jarosch — 2013-06-20T07:15:16

Forgive my ignorance, won't cloning of all the (small) repositories
also take 3 1/2 minutes or even more?


We splitted up some git repos at work and I made notes
of certain complex git commands. May be they might come in handy:

------------------------------------------------
Filter directory based on a whitelist:
git filter-branch --tag-name-filter cat --index-filter \
    'git ls-files -s |grep -P "\t(DIR1|DIR2)" \
    |GIT_INDEX_FILE=$GIT_INDEX_FILE.new git update-index --index-info &&
    mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' -- --all


Rename directories / remove prefixes (in this case source/):
git filter-branch --tag-name-filter cat --index-filter \
    'git ls-files -s | sed "s-\tsource/-\t-" \
    |GIT_INDEX_FILE=$GIT_INDEX_FILE.new git update-index --index-info &&
    mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' -- --all


Delete single files or directories:
git filter-branch --tag-name-filter cat --index-filter 'git rm --cached --ignore-unmatch -r -f CVSROOT Attic packages/Attic source/Attic' -- -

Git splitting

Michael M Slusarz — 2013-06-20T05:25:56

Now that the main portion of the x.1 releases are out the door, time  
to talk about splitting the Git repo.

(If there was any doubt we need to split, try cloning the Git repo  
from GitHub.  I did it today and it took 3 1/2 minutes.  Ugh)

Created a wiki page summarizing some agreements we have previously  
made on the list:

http://wiki.horde.org/Project/SplitGitRepo

Went ahead and did a test-run on converting Horde_Imap_Client to a  
separate repo.  Instructions on what I did are on the wiki page.   
Results of that can be seen here:

https://github.com/slusarz/horde-imap-client-test

This is something that can be easily scripted.  Although it is  
somewhat time-consuming - the 'git gc' command alone (necessary to  
reduce the repo size from 150 MB - > 2 MB) took approximately 19  
minutes of CPU time --  luckily I have an 8 core machine, so it  
finished in a more reasonable 2 minutes.  So this will probably be  
something we will need to run overnight when we convert all the  
apps/libraries.  I will

Re: Authentication session data cleaned by Kronolith

SSRI — 2013-06-19T12:01:06


We already use Horde_Auth's options to set session credentials. The  
problem arises with validateAuth() function which checks $_SESSION  
variables settled by the auth driver itself ( by verifying if external  
auth is still valid or not ). Is it possible to avoid Horde to destroy  
authentication informations settled by an auth driver ? If not, has  
the auth driver to create a new session each time validateAuth() is  
executed ?

Re: Fancy Horde/Imap_Client documentation

Jan Schneider — 2013-06-18T21:56:48

Zitat von Michael M Slusarz <slusarz< at >horde.org>:


Agreed.


Why not? Like I said, the current libraries pages on the website are  
just a start and could definitely be improved. The library's start  
pages should contain content like the Routes and Imap pages on  
dev.horde.org. And the overview should be more structured and cover  
better the different state of the libraries.


Well, not being happy with the design it not a valid reason to build  
another website. We agreed on this design and are going to stick with  
it for a while. There is no design everybody would be 100% happy with,  
but consistency is much more important.


The used to be updated automatically when we had our own CI server.  
Since then, this has to be done manually. We need to get the automated  
updating working again, if we start to write more documentation,  
because this will be updated at the same time.

Re: Fancy Horde/Imap_Client documentation

Michael M Slusarz — 2013-06-18T21:23:37

Quoting Jan Schneider <jan< at >horde.org>:


One of the comments I received was that http://www.horde.org/libraries  
is pretty much worthless from a "What does Horde have to offer  
approach."

* Way too information dense for a portal page for people looking to  
see whether our software will be useful for them.  It is presented  
more as a way to find documentation on a library that you already know  
exists.

* There is no distinguishing between our "glue-ish" libraries that  
would be of dubious value outside of Horde (Support, Mime_Viewer, even  
Prefs) vs. our libraries that blow away what PEAR can provide or, in  
cases like ActiveSync or Imap_Client, that *anybody* can provide.


I don't have a problem with that.  Maybe I'm confusing what you were  
saying previously: I don't want this rest documentation to be the ONLY  
documentation available and/or the initial presence.  We can use this  
as the default for many (most) of the libraries.  But there needs to  
be a way to allow a better (read: prettier)

Re: Fancy Horde/Imap_Client documentation

Jan Schneider — 2013-06-18T20:52:12

Zitat von Michael M Slusarz <slusarz< at >horde.org>:


It's just one part. Agreed, the docs for Argv are only for  
implementing it, not for advertising it. But that's all about *what*  
we write, not where.
http://www.horde.org/libraries/Horde_Argv/library is where the  
advertising should go, with more detailed documentation in  
http://www.horde.org/libraries/Horde_Argv/docs.


I don't understand what reST has to do with this. It's just an  
intermediate format, like the wiki markup. It's designed to be  
readable as-is though, so it's fine for bundling as technical  
documenation with the package. But at this point, the user already  
downloaded the libary and wants to use it, so that's fine.

Re: Fancy Horde/Imap_Client documentation

Michael M Slusarz — 2013-06-18T20:43:40

Quoting Michael M Slusarz <slusarz< at >horde.org>:


Let me make clear: I have no problems trying to prevent duplication of  
effort/documentation.  What I am saying is that I don't think the  
current setup is working at all in terms of presenting our products.

And that's not my opinion -- that's the feedback I've received from  
two different potential clients the last couple of months.

michael

___________________________________
Michael Slusarz [slusarz< at >horde.org]

Re: Fancy Horde/Imap_Client documentation

Michael M Slusarz — 2013-06-18T20:38:39

Quoting Jan Schneider <jan< at >horde.org>:


...except this is not what I am looking for.  This:

http://www.horde.org/libraries/Horde_Argv/docs/README

is not a useful format for *advertising* a component, IMHO.

I am NOT trying to document the entire library.  I'm trying to draw  
people into using it - or at least getting the word out.  I just don't  
think reST is appropriate for this.  At least that's what potential  
clients are telling me.

michael

___________________________________
Michael Slusarz [slusarz< at >horde.org]

Re: Fancy Horde/Imap_Client documentation

Jan Schneider — 2013-06-18T20:19:34

Zitat von Michael M Slusarz <slusarz< at >horde.org>:


Maybe I wasn't clear. I consider the wiki to be the source of the  
documentation, and doing what it does best: allowing easy editing and  
formatting of text. The location where we should point people to, is  
the website. The library section is just a start there and could  
definitely use some more love, but it's much better than maintaining  
yet another website.

So this is the workflow:
1) Editing in the wiki: http://wiki.horde.org/Doc/Dev/HordeArgv
2) Converting to reST:  
http://wiki.horde.org/Doc/Dev/HordeArgv?actionID=export&format=rst
3) Bundling with PEAR package:  
http://git.horde.org/horde-git/-/browse/framework/Argv/doc/Horde/Argv/
4) Building for website: http://www.horde.org/libraries/Horde_Argv/docs/README

Steps 2-4 are supported by horde-component.

Re: Fancy Horde/Imap_Client documentation

Michael M Slusarz — 2013-06-18T18:26:20

Quoting Michael J Rubinsky <mrubinsk< at >horde.org>:


For the record... this is exclusively what I use also.  But I  
guarantee we are in the minority - it does take quite a bit of prior  
Horde/PHP knowledge to understand things like file layouts to be able  
to do this.


This last 2-3 are probably the most important.  Right now, the  
documentation is trying to be geared to those people who want an  
alternative to imap's c-client library.  That's what I want to tailor  
the examples to.  I am thinking it might be useful to do some sort of  
mapping from c-client methods -> Imap_Client functionality.

The CONDSTORE/QRESYNC stuff is also what I am very interested in also  
- since we truly are the only solution that provides this.  So it's a  
balancing act of trying to get people to dip their toes into using the  
library vs. informing these people -- and letting the more advanced  
people know -- that our software can handle this also.

michael

___________________________________
Michael Slusarz [slusarz< at >h

Re: Fancy Horde/Imap_Client documentation

Michael M Slusarz — 2013-06-18T18:21:43

Quoting Jan Schneider <jan< at >horde.org>:


Right now I have to manually convert all the code to formatting (by  
putting in SPAN classes - ugh).  I really need either an automated way  
of doing this (I'd rather not have a javascript solution) or some  
location where I can insert the code and then copy/paste the HTML  
source.  That's really what was preventing me from providing other  
examples.


Unfortunately, I'm going to have to disagree with you.

As someone who has used the Horde_Argv documentation on the wiki, it  
*was* useful in terms of figuring out some of the details.  But there  
is NO way the Horde_Argv documentation, as presented on our wiki,  
would ever convince me to use that library over some other competing  
library.  Horde_Argv may be the most professional, bug-free,  
comprehensive argument parsing library out there.  But I would never  
know that from the documentation.  This is a limitation of using a  
wiki as the main page.

What I am trying to address is concerns I have heard from

Re: Imp and Horde_Stream_Filter

Michael M Slusarz — 2013-06-18T17:46:51

Quoting Remi Collet <remi< at >fedoraproject.org>:


Required.  Fixed for 6.1.3.

michael

___________________________________
Michael Slusarz [slusarz< at >horde.org]

Imp and Horde_Stream_Filter

Remi Collet — 2013-06-18T16:40:54

From package.xml

Horde_Stream_Filter is list twice.

in the "required" dependencies
in the "optional" dependencies

So, is it required or optional ?  ;)


Remi.

Re: Fancy Horde/Imap_Client documentation

Jan Schneider — 2013-06-18T14:54:57

Zitat von Michael M Slusarz <slusarz< at >horde.org>:


That's a great start! The examples could use a few more inline  
comments, to better explain which variable holds what, and what each  
used method returns.

Generally I think the documentation is spread in too many places.  
While the Routes layout looks nice, it's hard to maintain. And we  
already have the tools in horde-components to *distribute* docs to  
several places, while *maintaining* it in a single place.
Library docs should be completely maintained in the wiki. It's easier  
to edit, and contributions are much easier too. The horde-components  
script can pull those docs into the package's doc/ folder. From their,  
they will build website docs on www.horde.org. See Horde_Argv for an  
example.
This way the docs are available and in sync whereever the user needs  
them. And we don't really need a 4th place for docs.

Re: Fancy Horde/Imap_Client documentation

Michael J Rubinsky — 2013-06-18T13:46:21

Quoting Michael M Slusarz <slusarz< at >horde.org>:


Great start Michael.

I normally prefer to read the inline phpdoc while coding with a new  
library and I felt the existing phpdoc more than met my needs.  
However, if it helps, these are the areas that I personally focused on  
while developing ActiveSync email support, and would have liked to  
have had some more examples:

- Without giving a lesson on the purpose of MODSEQ values etc...  
examples on the use of MODSEQ values and the 'changedsince' parameters  
to fetch recently changed messages.

- Fetching messages that have VANISHED, with a description of why you  
should provide a list of known UIDs when requesting VANISHED messages  
(lesson learned the hard way for me).

- Fetching only certain MIME parts.

- Dealing with encoding issues.

- Using the various options of the search/fetch query object to change  
what is returned.