[wp-hackers] readme.txt spec

[Roy Schestowitz]

___/ On Tue 24 Oct 2006 22:25:47 BST, [ Mark Jaquith ] wrote : \___

> The readme.txt spec for plugins hosted on wp-plugins.org is getting
> some fresh air blown into its lungs and will soon be given purpose.
> Everyone and their dog will want their plugin to have a readme.txt
>
> So now seems like a good time to discuss the format and any
> improvements or clarifications that could be made.  Remember that the
> goal of this format is to be both human- and machine-readable.
>
> Some of the new additions to the format:
>
> * Minimum version (minimum version of WP that the plugin will work on)
> * Tested with (maximum version of WP that the plugin has been tested on)
> * Stable tag (for people who don't want /trunk/ to be regarded as
> stable, they can list a /tag/ that should take that role)
>
> Here is a sample readme.txt
>
>> === Plugin Name ===
>> Tags: tag1, tag2, tag3
>> Contributors: username, username2, username3
>> Minimum version: 2.0.3
>> Tested with: 2.1
>> Stable tag: 4.3
>>
>> Short description (250 words or fewer)  Regarding the above:
>>
>> * Minimum version is the lowest WordPress version that the plugin   
>> will run on.
>> * Tested with is the highest WordPress version the plugin has been   
>> tested on.
>> * Stable tag is OPTIONAL.  The default is to treat /trunk/ as   
>> stable.  But if you list a tag name here, that tag will be used as   
>> the latest stable version.
>>
>> == Installation ==
>>
>> 1. First installation step
>> 2. Second installation step
>> 3. Third installation step
>>
>> == Frequently Asked Questions ==
>>
>> = First FAQ question? =
>>
>> Answer to FAQ question
>>
>> * Bullets look like this
>> * Bullets look like this
>>
>> 1. Numbered lists look like this
>> 1. Numbered lists look like this
>>
>> `<?php // code goes in backticks ?>`
>>
>> = Another FAQ question? =
>>
>> Another FAQ question answer.
>>
>> == Screenshots ==
>>
>> 1. the filename is /trunk/screenshot-#.(png|jpg|jpeg|gif)  This   
>> text should be a description of the screenshot.
>
> The idea is to use Markdown syntax for the individual sections, so
> consult http://daringfireball.net/projects/markdown/syntax for that.
>
> What else would be of use?  Do you see any ambiguities about the format
> that need to be resolved?

Pardon my skepticism, but people rarely comply with the accepted  
structure (blame sloppiness and/or misunderstandings). Free-form text  
is a route to problems, confusion and---consequently---support burden.  
One alternative would be to validate or autogenerate a file using, for  
example, a Web-based form on WordPress.org.

Another common practice for settings files is to embed structural  
information in them, using some delimiters, e.g. brackets. You  
otherwise have ambiguities, so the composer need to escape reserved  
sequences (which are not familiar/human-readable). Why not retain all  
this data in some machine-readable form and have some function in  
WordPress which interprets the file and generates, let us say, some  
nifty HTML to serve as a reference?

There is a certain similarity here between properly-constructed HTML  
markup and some 'fluid' output (e.g. WYSIWYG versus typesetting).  
Better start from fine milk to get cheese and whipped cream (milk  
products). It would be hard to convert cream into cheese... structural  
semantics and natural language (or document) don't have a symbiotic  
relationship.

Best wishes,

Roy

-- 
Roy S. Schestowitz, Ph.D. Candidate in Medical Biophysics
http://Schestowitz.com  |  GNU/Linux  |     PGP-Key: 0x74572E8E
http://othellomaster.com - GPL'd 3-D Othello
http://iuron.com - proposing a non-profit search engine