Git-updater: Readme.txt parsing issues

[EusebiuOprinoiu]

Hello, Andy!

I'm using a readme.txt file that follows the WordPress conventions and I noticed there are some issues with the parser. ( inside the Details lightbox )

1. The "Tested up to" directive is ignored and a warning is displayed stating that the plugin has not been tested with the current version of WordPress. ( an old value is used - for some plugins it is 4.2.2, for others 4.4.2 )
2. The text written between "=" is not converted to headings as it should. On the Description and Changelog tabs it is displayed as is ( = Heading Title = ), and on the FAQ tab, as normal text ( Heading Title )
   In addition to this, if a changelog.md file exists that overwrites the the FAQ section generated from the readme.txt file, there is a big white space before the changelog history is displayed.
   I also noticed that custom sections like "== Installation ==" or "== Other Notes ==" are not generated. I'm not sure if this is the intended behaviour or not since your plugin has an Other Notes section.

Best regards,
Eusebiu Oprinoiu

[afragen]

Can you provide a URL to the readme.txt file?

Currently I'm using the parser from the plugin directory on .org.

In addition to this, if a changelog.md file exists that overwrites the the FAQ section generated from the readme.txt file, there is a big white space before the changelog history is displayed.

I intentionally give preference to a separate changelog file.

[EusebiuOprinoiu]

I can't provide a direct link from Github because I'm working with private repositories, but here is the file attached on OneDrive: https://1drv.ms/t/s!Ar7H53w9Xqu67QcjdfohuO7W7GGc

I don't have an issue with the fact .md files have priority. I even like it this way. My issue is the white space that is added before the content. My testing suggests that the white space is caused by the first heading. ( ## )

PS: The issue with the "Tested up to" directive might have been a caching issue. I see now the correct value is displayed.

[afragen]

I've seen this before and what I've found is that removing this first header fixes it. Since the info is going under the changelog tab having the first line in the file state this again is unneeded.

[afragen]

BTW this is picking up from the separate CHANGES.md file or how you've named it. Your readme.txt file looks fine.

[EusebiuOprinoiu]

It would have been nice to have that header there. ( My changelog.md file is made mostly for viewing on Github, not on the plugin details page ) But if there is no way to fix this issue, I'll remove it.
However, the main problem remains: The text between "=" is not converted to headings as it should.

And what about custom sections like "== Installation ==" or "== Other Notes ==" available in the readme.txt file? Shouldn't they be generated automatically? Or are they ignored on purpose?

[afragen]

Each section in a readme.txt file should have its heading in == not a = so == Supported Languages ==

[EusebiuOprinoiu]

Not exactly!
== is for making the sections / tabs at the top.
= is for making headings inside the sections. ( They are usually used inside the Changelog and the FAQ sections ) You can see that in the example provided by WordPress: https://wordpress.org/plugins/about/readme.txt

Pippin Williamson also has an article about this: https://pippinsplugins.com/how-to-properly-format-and-enhance-your-plugins-readme-txt-file-for-the-wordpress-org-repository

If you test a standard readme.txt file without any files like changelog.md to overwrite the content you will be able to see the issue.

PS: I believe before updating the parser a few versions ago the conversion used to work properly.

[afragen]

Can you provide an example of a plugin in the .org repo that uses this format. I'm quite certain that Pippin's write up was long before the parser was re-written.

[afragen]

BTW, the new parser accepts Markdown syntax and you could change your readme accordingly.

[EusebiuOprinoiu]

As far as I know, all plugins use this format.

Yoast SEO
Preview on WP.org: https://wordpress.org/plugins/wordpress-seo
Readme.txt content: https://github.com/Yoast/wordpress-seo/blob/trunk/readme.txt

WooCommerce
Preview on WP.org: https://wordpress.org/plugins/woocommerce
Readme.txt content: https://github.com/woocommerce/woocommerce/blob/master/readme.txt

When you are talking about the new parser, are you talking about the parser that comes with Github Updater or the one from WordPress.org? Because I want to use a readme.txt file that is 100% compliant with WordPress.org.

[afragen]

I take a deeper look tomorrow. I have a wedding to attend.

GitHub Updater is using the same updater code from wp.org. Take a look at the bottom of the README. I understand about want to ensure 100% compliance.

[EusebiuOprinoiu]

Sure! Don't let me keep you here! There's plenty of time to solve this! :)
Have fun! :)

[afragen]

Can you put your readme.txt file in a gist. I can't seem to access the OneDrive copy any longer.

[EusebiuOprinoiu]

I'm sorry about that. Here it is:
http://pastebin.com/FhTY3ESN

[afragen]

So I've used your readme.txt locally and I can confirm that the code does not provide for a conversion of = Supported Languages = to an <h3> tag.

As you can see in the .org parser there is no provision to parse this. https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/readme/class-parser.php#L265

I can confirm that changing = Supported Languages = to ### Supported Languages does work as the contents of all sections is later passed through the markdown parser.

I have no idea why this seems to function differently on .org than it does here. It really is almost identical code. The few minor changes I've made were to accommodate a string as file contents and to convert a line from PHP5.4 to be compliant with PHP5.3, https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/readme/class-parser.php#L309

I can absolutely confirm that the new .org parser works for a completely markdownified readme.txt file as I have several on the repo. https://plugins.svn.wordpress.org/the-events-calendar-category-colors/tags/4.5.1/readme.txt

[EusebiuOprinoiu]

Thank you, Andy!
I had no idea that WordPress.org has full Markdown support for readme.txt files. This must be something new. I'll convert all my readme.txt files to use this format.

[afragen]

I believe it is new and I'm very glad for it. Feel free to re-open this issue if there is anything else, otherwise please create a new issue.

Thanks.

[EusebiuOprinoiu]

Hello, Andy!
I'm reopening this issue. It looks like the parser has problems with the markdown format as well.
Level 3 headings (###) are not properly converted under the FAQ section.

[afragen]

Can you put the markdownified readme.txt on a gist for me?

[EusebiuOprinoiu]

Sure. Here it is: http://pastebin.com/ghG04TXF

[afragen]

I can confirm. Interesting that it works correctly on .org but not in _View details_.

[EusebiuOprinoiu]

As far as I can tell only the H3 tags are affected, in both standard and markdown versions.

[afragen]

I wonder whether something in plugins API strips the markup in _View details_?

[afragen]

So I've done a deep dive and I found the problem. Bug really. It's all in core. The .org parser converts a properly formatted FAQ into a description list <dl><dt><dd> tags. BTW, this is the new parser for .org as it undergoes a remodel. The install_plugin_information() which displays the information then dutifully strips out these tags as they are not among the allowed tags.

I will submit a trac ticket to fix this but I have no idea how it will play out. What this means is if I use the .org parser, and I am, this will be an issue unless fixed in core.

[afragen]

That being said, I will adjust the parser in this project so it displays the question in h4 tags.

[afragen]

Update to latest develop 6.0.0.3, refresh cache, and you should see the changes.

[EusebiuOprinoiu]

Thank you very much, Andy!
The strange thing is I haven't noticed any issues with the plugins hosted on WP.org. Somehow everything is converted properly when a plugin is hosted on the official repository. I really hope they'll take your fix into consideration.
And please, place a link here to the trac ticket when you submit it. I'd like to follow it.

[EusebiuOprinoiu]

I did a test with the latest version from the development branch and it doesn't seem to work.
I see the latest version is 6.0.0.2. I can't find version 6.0.0.3 anywhere. Did you revert the changes?

[afragen]

I didn't revert I just forgot to push the commit. 👊
It should be there now. I will post the trac ticket here once I make it.

[EusebiuOprinoiu]

Thank you, Andy! It works! :)
There is also another small issue with code blocks. I presume the problem is in the WP.org parser as well.
It looks like for readme.txt files with LF line endings all code blocks are displayed on the same line. If I'm not mistaken the old parser didn't have this problem. Perhaps you could raise this issue as well when you open the ticket.

[afragen]

I've seen the code block issue. I haven't dug into it but when I find out I'll submit a trac ticket for that too.

[afragen]

So after some discussion with @dd32 on Slack, the install_plugin_information() may see an update. If it does I'll adjust back, otherwise I plan to keep it where it's at.

The reason that = Supported Languages = parses on .org and not locally is that it's the Markdown library .org uses that's parsing it, not the parser. I use a different Markdown parser than .org does.

[EusebiuOprinoiu]

Thank you Andy, for keeping me informed.
Have a nice day!