Home Messages Index
[Date Prev][Date Next][Thread Prev][Thread Next]
Author IndexDate IndexThread Index

Re: [wp-hackers] readme.txt spec

  • To: wp-hackers@xxxxxxxxxxxxxxxxxxxx
  • Subject: Re: [wp-hackers] readme.txt spec
  • From: Roy Schestowitz <r@xxxxxxxxxxxxxxx>
  • Date: Wed, 25 Oct 2006 00:23:39 +0100
  • Delivery-date: Wed, 25 Oct 2006 00:23:40 +0100
  • Envelope-to: s@schestowitz.com
  • In-reply-to: <4B4CBC8D-28FA-425A-AB1B-92EB8445CEA5@txfx.net>
  • References: <4B4CBC8D-28FA-425A-AB1B-92EB8445CEA5@txfx.net>
  • User-agent: Internet Messaging Program (IMP) H3 (4.1.3)
___/ 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

[Date Prev][Date Next][Thread Prev][Thread Next]
Author IndexDate IndexThread Index