I have tested this item ✅ successfully on b0e9e8b

?

IMO the description field of an extension is NOT a miniature README on what the extension is. It shouldn't be much more than a high level summary of what it does. I agree the current text is definitely minimal at best, but don't agree that it needs to become a miniature documentation manual.

If it's really that urgent to include this stuff right in the Joomla installation, at best it should be done with a new field and text string. Also, this type of information is exactly why there is a help button on all core extensions.

I have tested this item ✅ successfully on b0e9e8b

I agree we need a better description for this plugin but this isn't it.

From the style guide

Avoid over-communication

Be explicit wherever necessary but don't explain the obvious. On the web
scanning is the norm and too much text weakens the effectiveness of the
message - it does not enhance it.

Miniature description manual ?
my descriptions are far from a miniature readme, if you remove the line breaks that increase readability then we can see how small it is

• my text is tiny compared to what could be written about caching

i thought of every phrase i wrote, and considered , if it could be removed.

I have answered in my forum more several dozens of threads about for Joomla caching over the years

@mbabker
I can understand you having worries about code changes,

but worrying of even descriptions ?
having cryptic plugins with non-existent descriptions,

• that squeeze us out of time to explain things to users,
• and frustrated users that do not understand why things do not work, and blame things for being broken

is better ?

if we want to make it smaller, then we can remove the line breaks and the dashes and use comma and full stops. Then it will look much small but less readable, and less understandable

Brian said it a bit more eloquently. My comments were a bit exaggerated. I don't think the description needs to be as long as you've made it here. Yes, it can be improved upon, but I don't think this should be the way it's done. Plus, "extra" information like this is why we have the help screen system in place. When you REALLY need these longer descriptions, it should probably be stored as content in the docs wiki and easily referenced via the help buttons in the backend.

The Joomla backend interface shouldn't be filled with long descriptions describing how to use each component of it. If we're doing so, we're failing. The descriptions should be kept simple so the user understands what the extension is and does. The part where you start explaining differences in the configuration values to me goes beyond what the description should be doing.

@mbabker
I totally agree with you about long descriptions and about docs wiki,

but i do disagree with you, about what should be considered long

what i have seen from users, is that after things do not work, majority of them will read the description

• and you will get less forum threads opening
• and less frustration

furthermore, for every user that complains that things do not work, there are a couple of others just abandon it, without posting a complaint, (after googling it to find solution and finding much longer descriptions that they do not always understand, or they do not want to read)

Yes, I get that. But I still do not think that the description fields should be turned into a miniature documentation source. If the descriptions and tooltips have to have an extended text blurb about the various use cases and configuration possibilities, then we've screwed up. Period.

Yes, I get that cache is a complex subject. That still doesn't change my mind that the description should be a full blurb explaining the page cache plugin's relationship to the global configuration cache, include information about how the page cache clears itself, or even explaining the performance effects of enabling the plugin. That all to me is documentation and belongs in a documentation source. If you have to start introducing line breaks into the extension description fields or tooltips, to me that's a red flag that you're trying to put too much information into that source.

Also take into consideration that the extension description is a tooltip in other views (such as the example below from the Extensions: Manage page with the .sys.ini file for the plugin patched with the same change). This change makes the tooltip unusable because it is far too long.

I;m not even sure I agree with the text

On 8 July 2016 at 14:43, Michael Babker notifications@github.com wrote:

Yes, I get that. But I still do not think that the description fields
should be turned into a miniature documentation source. If the descriptions
and tooltips have to have an extended text blurb about the various use
cases and configuration possibilities, then we've screwed up. Period.

Yes, I get that cache is a complex subject. That still doesn't change my
mind that the description should be a full blurb explaining the page cache
plugin's relationship to the global configuration cache, include
information about how the page cache clears itself, or even explaining the
performance effects of enabling the plugin. That all to me is documentation
and belongs in a documentation source. If you have to start introducing
line breaks into the extension description fields or tooltips, to me that's
a red flag that you're trying to put too much information into that source.

Also take into consideration that the extension description is a tooltip
in other views (such as the example below from the Extensions: Manage page
with the .sys.ini file for the plugin patched with the same change). This
change makes the tooltip unusable because it is far too long.

[image: screen shot 2016-07-08 at 8 41 57 am]
https://cloud.githubusercontent.com/assets/368545/16689298/ef34f554-44e7-11e6-8049-a7e2795470ae.png

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
#11052 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/ABPH8XtAeycG1NvdeugqCz8tICcp6ryPks5qTlP6gaJpZM4JH57y
.

Brian Teeman
Co-founder Joomla! and OpenSourceMatters Inc.
http://brian.teeman.net/

About agreeing with the description text,
of course you can corrected it, at the places that needs correction

• about tooltip, i would say that the tooltip code needs fixing, check via strlen, if longer that nn characters, then if it is, strip tags and cut the text, but keeping the new lines (replace <br/> with \n strip tags and cut and then re-add line breaks)

also why does the plugin edit form has a dedicated TAB for description if it is meant to be 2-3 sentences ?

also why does the plugin edit form has a dedicated TAB for description if it is meant to be 2-3 sentences ?
Show all checks

Because third party extensions like to use long descriptions I guess. I can't say I'm a fan of that design decision but IMO it isn't a good one. If you need long help screens or text like that, create dedicated help platforms and link to the documentation. I don't think that the CMS should be self-documenting by shipping large blocks of text in the admin UI. But as I keep saying, usually people ignore my thoughts these days anyway to YMMV.

3rd party will even add pictures ... to it !

about tooltips it can be fixed like this (and then it can be used elsewhere too):

1. Convert html entities to characters so that they will not be removed ... by strip_tags
2. Add whitespaces at start/end of tags so that words will not be joined
3. Add \n after <br/> </p>
4. Strip html tags
5. Replace multiple newlines with single
6. Replace multiple spaces, tabs with a SINGLE whitespace so that text length will be calculated correctly
7. Calculate length according to UTF-8 encoding, and return the Full string together with its HTML tags if within limits
8. If cut off is needed, do it and append ' ...'
9. Reencode HTML special characters, (but do not encode UTF8 characters)
10. Replace \n with line breaks <br/>

in anycase you can just recommend a text that is good enough and shorter, thanks

Honestly, I don't have any suggestions that don't start sounding too documentation like. And "Adds support for caching full page requests." isn't going to cut it since apparently there is a need to explain the difference between the page cache plugin and the global cache configuration and the fact that as a plugin it isn't integrated into the core processes dealing with cleaning cache on content save.

Sidebar: You honestly couldn't add support for the onContentCleanCache event to the plugin either to cope with that last part of the above statement because the cache keys/groups don't contain enough data, so you'd have to either flush the entire page cache on a save event or stick with status quo unless you can devise a system that makes that cache item aware of every group it is composed of.

As added by mbaabker & brianteeman very long winded, if it's missing anything it could possibly be one word and a note, suggestion below.

Provides whole page caching

Note: This plugin works independently of Conservative/Progressive Caching in Global Configuration

This PR has received new commits.

CC: @killoltailored, @RonakParmar

This PR has received new commits.

CC: @killoltailored, @RonakParmar

Made it, much more compact, but still good enough

@brianteeman
@mbabker

yes i made wrong description for it

I checked the code, the parameter sets a not-modified header and exits

        $app = JFactory::getApplication();

        // Send not modified header and exit gracefully
        header('HTTP/1.x 304 Not Modified', true);
        $app->close();

i have corrected the parameter description, please review

https://github.com/joomla/joomla-cms/blob/staging/libraries/joomla/cache/controller/page.php#L68-L74

https://github.com/joomla/joomla-cms/blob/staging/libraries/joomla/cache/controller/page.php#L202-L209

Too tired to look at it properly today. been on the tracker all day. I will take a pass at making it english and non-tech user friendly later this week

I have tested this item ✅ successfully on c61df92

Like the more in dept description...

I have tested this item ✅ successfully on c61df92

Test OK!

@brianteeman please take a decision here ;)

The English isn't good enough to merge I will try to find some time to
improve on it although I still have my doubts that this text is a tooltip
and not appropriate

@zero-24 and others

I have taken another look and I still don't like the changes in the description or the tooltip. They should be ONLY describing what something does and not describing what something else does or why something else is better.

The only part of this PR that I would be ok with is adding

Note: This is not to be confused with conservative / progressive caching

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/11052.}

@brianteeman

What about now ? i have removed most the added text, leaving only:

Provides page caching, not re-creating the HTML of pages <br/><br/>
Note: This is not to be confused with <b>conservative / progressive</b> caching"

The first line still doesn't make sense to me. It says it doesn't do
something. Do what does it do

Can you rewrite it ? and i will commit it

I don't know what you are trying to say

On 5 Nov 2016 10:28 a.m., "Georgios Papadakis" notifications@github.com
wrote:

Can you rewrite it ? and i will commit it

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#11052 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABPH8fK-CWpXGx-KMpJ-sNGtHc2FDzzcks5q7FpogaJpZM4JH57y
.

Something like:

Provides page caching, Joomla will cache the full HTML of every page, <br/>
this includes both component and modules HTML<br/><br/>

Note: This is not to be confused with <b>conservative / progressive</b> caching,
that is done per component / per module

Can someone help ? suggest something better ?

OK Now I understand more clearly.
No need to say "this includes..." Its either the full html or its not

On 5 November 2016 at 10:44, Georgios Papadakis notifications@github.com
wrote:

Something like:

Provides page caching, Joomla will cache the full HTML of every page,

this includes both component and modules HTML

Note: This is not to be confused with conservative / progressive caching,
that is done per component / per module

Can someone help ? suggest something better ?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#11052 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABPH8XkHJm4bYCL-jFNZdnn7l_AXo7Qrks5q7F4ngaJpZM4JH57y
.

Brian Teeman
Co-founder Joomla! and OpenSourceMatters Inc.
https://brian.teeman.net/ http://brian.teeman.net/

I have tested this item ✅ successfully on 75235b0

I have tested this item ✅ successfully on 75235b0

RTC

I'm taking off RTC until we have a final en-GB review / approve.

Honestly, I do not understand this description. It is no help at all.

PLG_CACHE_XML_DESCRIPTION="Provides page caching, not re-creating the HTML of pages <br/><br/> Note: This is not to be confused with <b>conservative / progressive</b> caching"

I am going to close this issue as the new description seems to not clarify the use of the plugin any further. Best would be to add the original description to the wiki page as it is available already behind the Help button.