17 replies to this topic

[Randy]

May we please have a text area with the content of the snippet in it just like the old snippet library?

This is helpful to evaluate whether a snippet will meet you needs without the additional steps necessary to download it or several others until you find the one that most closely meets you needs.

Thanks,

[Dean]

I'll have a ponder over this one, to see how we can achieve it.

The alternative is to add the php code into a [ codebox ] [ /codebox ] tag when the user creates a tag.
BUT.. It's whether or not the user would remember to update the Download file that is attached to the download also - as the downloads are versioned, so a user can see the progress that is made between the versions.

Feel free to post your request over at the IPS forums (the developers): Here
This is what I think would be a great addition to the IP.Download Manager: If the attached file is a text/html/php attachment, then the Download Manager should display the file content within <textarea></textarea> tags, for users that have permission to download it. As long as the Manager doesn't parse the PHP, it should keep the script safe from XSS (we are regularly targetted).

[Randy]

I agree the results of a codebox would be variable.

Waiting for ip.converge to generate my account so I can make the request.

[Randy]

I have another suggestion for the snippet library.

Why not use Etomite? With a separate database (not table) we could store the snippets and templates outside the Eto realm. We could establish very specific documentation criteria through the use of form validation. This would establish consistently documented snippets.

This would then allow us to automate the inclusion of individual snippets directly into the documentation portal. This would be a simple matter of pulling the data and formatting it for the page. Since it would all be consistent they would all look the same. Cool!

I recommend keeping a file based copy. Perhaps there would be a reason to put them into the database, but that isn't completely necessary. Since you now would control the medium, we could easily read the file contents and push it into a <textarea> for display.

Just a thought...Eto can do all this with ease.

[Jelmer]

Without already having an opinion about this, putting all the snippets directly in a database would work well with an idea I read somewhere about a future Snippet Repository to automatically have your snippets up to date...

[mikef]

Randy, on Apr 16 2007, 05:40 PM, said:

I have another suggestion for the snippet library.

... We could establish very specific documentation criteria through the use of form validation. This would establish consistently documented snippets.

While I understand the reasoning behind this, the most likely result would be a reduction in the number of snippets donated.
Its hard enough for many people writing stable PHP code, without having to also write documentation according to specific rules (when many of the snippet authors don't have English as the first language).
The authors of some existing snippets are probably also no longer around.

[Dean]

But - then try integrating with IPB. Thats where your ideal plan becomes unstuck.

It's what we used to do... but how long has the main snippet library been down for now?
We upgraded IPB (Security Fixes etc), the two people that threw it together scarpered, one promised to fix it, and then never bothered doing it. We hung around for ages, empty promises were given, nothing came. It's only recently that I finally made the decision to use the IPS one, which is always going to work.

What I'm not going to do is rely on someone's third party code to try and bridge the two items.

But - instead of changing what's written, why don't you write a front end that pulls the file content stuff from the IPS Download Manager?

[Randy]

Please don't mistake my input here...I'm not questioning any decisions being made. I completely misunderstood the architecture. I thought the documentation site was a pure Etomite based site that could be 'used as built' to do these things. Didn't realize it was integrated with IPB. So again, I'll defer.

[Randy]

Jelmer, on Apr 16 2007, 11:56 AM, said:

Without already having an opinion about this, putting all the snippets directly in a database would work well with an idea I read somewhere about a future Snippet Repository to automatically have your snippets up to date...

Yes, but it seems there are more ideas blocking the beauty of this concept than enabling it...too bad.

Edited by Randy, 16 April 2007 - 06:36 PM.

[Dean]

What part are you referring to - I was referring to the Snippet Library in this thread - as it's part of IPB.

The documentation site is an Etomite install :-)

If you can show me something that is safe from exploits, can integrate with IPB, and is not going to break when we upgrade IPB, then I will happily take a look. Oh, and add the requirement that more than two people know what the code does (for maintenance) into that mix :-) Then we don't get bitten.

If it helps at all, I can setup an account with a plain IPB Install, an Etomite Install and a IP.Download install and you can play with it?

[Randy]

Dean, on Apr 16 2007, 02:03 PM, said:

What part are you referring to - I was referring to the Snippet Library in this thread - as it's part of IPB.

The documentation site is an Etomite install :-)

What I meant in this post:

Quote

Why not use Etomite? With a separate database (not table) we could store the snippets and templates outside the Eto realm. We could establish very specific documentation criteria through the use of form validation. This would establish consistently documented snippets.

This would then allow us to automate the inclusion of individual snippets directly into the documentation portal. This would be a simple matter of pulling the data and formatting it for the page. Since it would all be consistent they would all look the same. Cool!

Was to build an Etomite solution for a snippet library that is part of the Documentation site. The solution would be in the form of a snippet (or two) that would utilize the Eto API to access a separate database+tables that would store the information about the snippets. The separate database is specifically to prevent XSS attacks from posted material. The cataloging of the snippet could be through a form interface that would collect the following mandatory fields:

[indent]

• category
  
• name
  
• short description
  
• calling parameters
  
• variables used
  
• css info
  [/indent]

plus a file upload with only .php files allowed. [For Mike: I hear you about the documentation stuff, but this list is all I was really referring to] I would include an optional longer discription <textarea> for a more complete description of the snippet if folks wanted more information. The presentation could take any form then because Eto would be driving the snippet catalog and not IPB.

That way, folks familiar with Etomite would intrinsically know how it works and how to maintain or enhance the tool. For instance, Jelmer's recollection of the 'automated update' or even 'automated install' of snippets in future releases of Etomite would now be a possibility because Etomite is completely controlling the catalog rather than integrating it with IPB.

Hope this clarifies things.

[mikef]

Would probably work for most snippets, but not necessarily the more complex.

Have a look at the EtogalThumb snippet documenation - this is the bare minimum I consider useful in documenting this snippet and how to use it, and put into a textbox (without formatting) it would be unusable.

Also some snippets actually need more than one file (and aren't catered for well in the previous or current systems either), and not necessarily all php - eg CrisD's new snippet for Etogal galleries, which needs a chunk to hold the fomatting for the table output.



It would be a lot better than nothing, though!

[Randy]

First, I've personally implemented your work and appreciate your ability to bring it all together as you have. It adds great value to the Etomite community of users.

Wow, I'm bewildered. In one post you complain because I had the audacity to mention documenting something and in this post you complain because I took a minimalist approach and didn't provide enough.

Admittedly your gallery is a beast and I wouldn't qualify it as a snippet. You know as well as I do that Ralph is attempting to create a pluggable architecture that allows more advanced capabilities like your gallery to be included or excluded as part of the install rather than as an overly complex snippet. That is the answer to your personal snippet submission and those that tag along with it.

I'm attempting to address one or two standard deviations from the mean...you're way out in the 99th percentile with your work and this scheme admittedly would not benefit you or the users of your snippet. I would think future capabilities as complex and involved as yours would qualify for treatment as community maintained "Plug ins" rather than simple snippets.

I see no reason chunks specifically associated with snippets couldn't also be stored as part of the catalog.

Good ideas.

[Ralph]

Yeah, as Randy mentioned, and as many of you may already know from conversations with me, some sort of Plugin's or Modules or something is in the works... I haven't really nailed it down yet and maybe there will be more than one method of implementing add-on's...

It's good to see some constructive debate going on... I'd be chiming in a bit more but I've been busy trying to get some cash in the currently empty bank account... Being reduced to a single income household has put a strain on the amount of time that I have been able to invest into the project, much to my dismay...

[mikef]

All I meant was rules for documentation have to cater for exceptions. (I suspect some of the events snippets would fall into exceptions too. )

Your documentation rules aren't trying to cover too much, and so will work for the majority, provided people are prepared to write them. I think you've hit a good balance on what to require - without that information moderately complex snippets would be too hard to use anyway, and so would yield long support threads.

The most complex snippets will still need individual treatment, which could be provided with a link to a handwritten page for additional info. (I'd find writing HTML easier than writing bbcode, to be honest. The basic formatting on my documentation pages all stems from Frank's original documentation.)

Consider my reservations withdrawn ...

[Randy]

Mike,

What I'm advocating in 'the other thread' is documenting the snippets within the confines of the documentation site. So each snippet would have it's own page the author could use to document the snippet anyway they chose. Those mini snippets could get a way with the minimum inputs during the upload. Those of you with complex stuff could be free to expand.

I don't know about html vs. bbcode yada yada....I'm more interested in helping create a congruent set of documentation that everyone can rely upon and trust. This is opposed to trying to find an obscure answer strewn throughout 125 random posts (search on etogal in the forums). All of which are based upon three generations (or more) of the snippet with no idea what relates to the current version or twenty two versions ago. (Have I mentioned that forums stink for documentation?)

A single documentation page within the documentation site would be relevant to the latest version of the snippet. If no one was around to update the documentation or it became mismatched with the snippet it referred to, I would recommend suspending the availability.

Of course I'll catch flack for even suggesting that out dated, unmaintained, stale, dysfunctional code be ...ooo here it comes.... removed from public consumption.

[mikef]

Randy, on Apr 16 2007, 11:37 PM, said:

Have I mentioned that forums stink for documentation?

maybe ... can't disagree!

The real problem there though isn't really initial documentation, but ongoing support, and its a lot of effort to go through the forum threads and extract the generally relevant bits and put them into a FAQ. (The Etogal initial documentation is all in one folder, with very few posts ... the rest is explanations, finding solutions to odd problems with specific platforms, misunderstandings, feature requests and excuses for not doing them, etc.)

And I remember how hard it was to get the current Etomite documentation assembled!

[Randy]

I have directors and SVPs from multi-billion dollar companies tell me (word for word) the same thing you say below over and over and over again. The most previous, a mere two weeks ago, was one of the Blue Cross and Blue Shield organizations that made over $1B last year.

mikef, on Apr 16 2007, 06:22 PM, said:

And I remember how hard it was to get the current Etomite documentation assembled!

The reasonable response to the statement is: "What steps have you taken to ensure you won't have the same trouble again."

The answers vary but the outcome is generally the same...not much. All I'm trying to do is prevent this truth.

That will be the same answer 1,2,3,5,7 years from now with this project too. Rationalizations, excuses, finger pointing, lack of accountability, and in open source projects the "not invented here syndrome" all contribute.

It's too bad.