[wp-trac] [WordPress Trac] #53527: Update readme documentation to better reflect code usage, and clarify a discrepancy with the Readme validator

[WordPress Trac]

#53527: Update readme documentation to better reflect code usage, and clarify a
discrepancy with the Readme validator
-------------------------+-----------------------------
 Reporter:  bedas        |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  Plugins      |    Version:  5.7.2
 Severity:  normal       |   Keywords:  needs-docs
  Focuses:  docs         |
-------------------------+-----------------------------
 When submitting a Plugin readme.txt file, the instructions
 [here]https://developer.wordpress.org/plugins/wordpress-org/how-your-
 readme-txt-works/ does not specify that we need to add the code within
 `<pre><code></code></pre>` tags.

 Instead, it states that code "goes within backticks"
 **This is only correct for one-line code.**
 **For multiple lines of code (for example an "example filter") this is not
 working, and we need to use code and pre tags instead.**

 It would be good to update/reflect that on the DOC, so no one needs to
 "test what works"

 Here is a text suggestion, where in
 https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-
 works/#example-readme, the line `<?php code(); // goes in backticks ?>`
 becomes
 > `<?php code(); // goes in backticks ?>`
 > `<pre><code> //larger code goes into pre and code tags`
 > `<?php add_filter( 'hook', 'example', 10, 1 );`
 > `function example(){`
 > `    //do stuff`
 > `}`
 > `</pre></code>`


 ----


 In the same doc, https://developer.wordpress.org/plugins/wordpress-org
 /how-your-readme-txt-works/#readme-header-information does not mention
 anything about the `Requires PHP` field.
 However, when we validate a readme with
 https://wordpress.org/plugins/developers/readme-validator/, then the
 following warning will appear:
 [[Image(https://files.slack.com/files-pri/T024MFP4J-
 F026PG6KYTB/screenshot_2021-06-27_at_19.09.53.png)]]
 >The Requires PHP field is missing. It should be defined here, or in your
 main plugin file.

 That warning might confuse people (it did confuse me).
 This could perhaps be mentioned in the DOC, that when we use the
 validator, we can ignore this warning, as the field is "obsolete" as it
 seems this field was once added to readme in past by mistake, and while
 this has been corrected, the validator does not reflect that. Thus a DOC
 mention could help clarify that.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/53527>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform