[ANN] PEAR Channel and Git Repository Mirror for PHP Markdown & Extra

[Michel Fortin]

Le 2007-08-31 à 20:33, Allan Odgaard a écrit :


> On Aug 31, 2007, at 10:22 PM, Michel Fortin wrote:

>

>> [...]

>> So today I announce two additional ways of grabbing PHP Markdown  

>> and PHP Markdown Extra. The first one is a PEAR channel [...]

>

> Since I was one of those requesting this, here’s my feedback: I  

> think PEAR is badly suited to my purpose. For WordPress the file  

> (markdown.php) needs to be in wp-content/plugins or so *and* I need  

> to edit the file for my configuration changes (e.g. having it  

> output HTML tags rather than XHTML).

>

> The location thing can probably be solved with a symbolic link,


Just a question, wouldn't you have to do the same trick with Subversion?


> but while I didn’t experiment with PEAR, I do not think it supports  

> upgrading a package where the user has local changes


It does not, indeed.


> -- maybe it would be worth considering getting preferences  

> optionally from a separate file


That is worth considering, especially since it would be so easy. A  
configuration define like this one:

     define( 'MARKDOWN_EMPTY_ELEMENT_SUFFIX',  " />");

could become this:

     @define( 'MARKDOWN_EMPTY_ELEMENT_SUFFIX',  " />");

Notice the error suppression operator `@`. What this means is that  
you can define the constant before including PHP Markdown and it  
would not complain and use your previously-defined value instead  
(since in PHP `define` won't override an already-defined value).

In short, you could add that line in the WordPress config file and be  
done with it.


> (it’s no real problem for me though, just mentioning that maybe it  

> is not ideal, especially if one install of PHP Markdown is shared  

> among multiple users/systems).


That may be a good-enough reason for taking the route above. Also,  
you're not the only one updating PHP Markdown as a WordPress plugin;  
I'll bet half the people using it don't know how to use a version  
control system. Even when updating by downloading and installing the  
file manually, having to apply the changes each time is just error- 
prone and time-consuming.


> Anyway, PEAR might be good for other setups (so I am not saying  

> remove it, just that for me, this seems to be no better than the zip).


PEAR is good especially for those using it as a library in their own  
programs. `pear upgrade-all` will probably prove very handy to those  
already using PEAR-installed libraries.

That might not be you indeed, but perhaps allowing the configuration  
to be in a separate file would change your mind.



>> The second method for grabbing PHP Markdown is to use the Git[^1]  

>> repository mirror available at <http://git.michelf.com/php- 

>> markdown/>.

>

> This works for my purpose, i.e. I can just git pull and have git  

> merge in my local changes etc. Thanks!

>

>> [...] The repository contains two branches: the "master" branch  

>> contains the code for PHP Markdown; and PHP Markdown Extra is  

>> maintained in the "extra" branch.

>

> I wonder how you plan to maintain this.


I update PHP Markdown on the master branch, update PHP Markdown  
Extra's specific stuff in the extra branch, then merge in the extra  
branch the changes done to the master branch. It's pretty easy:

     git checkout master
     ... do some changes ...
     git commit -a
     git checkout extra
     git merge master

and the changes are now found in Extra too.


> Since the two branches are newer going to be merged, but Markdown  

> Extra is supposed to always be a superset of Markdown, ideally you  

> would re-base extra each time you update master -- but because you  

> make the extra branch public, you can’t do that (by convention,  

> since a re-base will remove nodes, causing a problem when other  

> fetch changes for the extra branch) so instead you will have to  

> cherry-pick the patches applied to master.


Cherry-picking was what I was doing before. I'm not going back to that.

Even if having two separate parser classes makes things much easier,  
the process is still error-prone when updating non-parser stuff. I've  
made some mistake recently while copying over the WordPress interface  
from one version to the other for instance.

The worst inconvenience of merging is a conflict that pops out in the  
version history in the comments at the bottom. Perhaps I'll just  
remove that section, it's pretty useless now anyway since the details  
are found only in the readme file.


> I guess cherry-picking each time will work, but it seems like maybe  

> the two versions of markdown.php should not be maintained as two  

> separate branches, as those branches will effectively only share  

> one parent node (the root node) and have lots of identical  

> descendants, but with no tie between them.


They do no, since I'm merging.

Well, except in the case of the Readme file. Changing the name caused  
that; perhaps it could have been otherwise if I did change the name  
and update the file in two distinct commits. If so, it's still fixable.


> So I would suggest just having one source with PHP’s equivalent of  

> #ifdef MARKDOWN_EXTRA or similar, for where they diverge.


My original idea was to have three files: one for the Markdown  
parser, one for the Markdown Extra parser, one for the plugin  
interface. Then the plugin file I distribute would be "built" from  
that, and I could also distribute it as separate files, a form more  
appropriate for a library.

I'm not quite sure what I'll do about that in the future, but right now


>> The Git mirror should be particularly interesting to other  

>> developers who want to follow PHP Markdown's development and track  

>> changes made to it. Take note that I offer no guaranties about the  

>> stability of the code on the head of any branch, so be careful  

>> with what you get there.

>

> Could you introduce a ‘latest’ tag which is the latest release  

> version? That would make it easier to track.


I don't think a tag would work, not with Git. Read the "Discussion:  
On Re-tagging" section of the `git-tag` man page: <http:// 
www.kernel.org/pub/software/scm/git/docs/git-tag.html>.

What would work is a branch I would merge with, or rebase to, the  
latest stable version each time a release is made.

Or else, you could "mix" PEAR and Git in a strange manner. First get  
the number of the latest stable version by looking at <http:// 
pear.michelf.com/rest/r/markdown/stable.txt>, then by putting "v" in  
front of that version number you get the corresponding tag in the Git  
repository. (For PHP Markdown Extra, look at <http://pear.michelf.com/ 
rest/r/markdownextra/stable.txt> and use "x" as the prefix.)


Michel Fortin
michel.fortin at michelf.com
http://www.michelf.com/