How difficult would it be to add a ReadMe to hg serve?

[Boggess, Rod]

On the one hand, I'm not sure why you didn't choose XML for starters, since it's ascii and human readable, with parses already available all over the place. That said, if there is a way to already to specify a readme file in a conf (or ini, for windows) file, you could simply assign the bugs file to that readme file, and the web server would serve it as a text file, the browser would receive it with no markup, and display it just like notepad (or Emacs or whatever text editor floats your boat).

What I had in mind is a little trickier. I was planning on loading an honest-to-goodness html page, and in that page, I could put some javascript. One thing that javascript would do is an asynchronous request for an additional file from the server, and I'm going to cheat here and take advantage of the fact that the web server is a file repository, and specify that it download from a project-standard relative path to request a copy of b's bugs file. Here's where the formatting matters.

If I have a text file that contains a javascript structure, I can absorb that data directly into the javascript and just start using it to build a TODO list in a box. Using an asynchronous request, this is called JSON. The javascript structure is ascii text, but it would be cranky when humans edited it without fully understanding the format.

Alternative, I could request an XML data file. This is called AJAX. It's also in ascii text, but is more tolerant to human editing. In both cases, it's possible to parse the data efficiently because json doesn't require parsing, and xml has in-built parsers for operating systems and browsers. You could create a custom function in javascript to parse your data format, but it's slow (because it must run inside the browser), wasteful (because I'd have to write all the code), and fragile (because the smallest change in format to the file causes everything to break).

So, if this can be made to work through either a template or if the developers here are willing to add serving of a ReadMe file as part of hg serve, that would be awesome, and you could simply server a no-frills, plain ascii bugs file. (Sorry, but because you placed the expanded information in a separate file, it would be nearly impossible to make that show in the same page with the default bugs data.) Furthermore, my solution is not overly portable because I have to issue a second request to hg serve for the bugs.xml file and my html page has to include all the javascript to make the AJAX request and parse it. If you switched the format of b to use XML it would help, but that second file would still be held together with bubble-gum and twine (based on a specific relative location and file name).

Now you can see why I wanted to fork b and create my own xml output. I would have contacted you first, but this is all for naught if I can't even display the ReadMe file, and at the moment, I can't. (A config setting for b, though, that used XML data for the backend might be equally acceptable and wouldn't cause any compromise in b's simplicity.)


-----Original Message-----
From: Michael Diamond [mailto:dimo414 at gmail.com]
Sent: Sat 10/20/2012 3:47 PM
To: Boggess, Rod
Cc: Kevin Bullock; mercurial at selenic.com
Subject: Re: How difficult would it be to add a ReadMe to hg serve?
 
On Fri, Oct 19, 2012 at 4:37 PM, Boggess, Rod <rboggess at tenovacore.com>wrote:

> ** **
>
> ** **
>
> *From:* Kevin Bullock [mailto:kbullock+mercurial at ringworld.org]
> *Sent:* Friday, October 19, 2012 4:03 PM
> *To:* Boggess, Rod
> *Cc:* mercurial at selenic.com
> *Subject:* Re: How difficult would it be to add a ReadMe to hg serve?****
>
> ** **
>
> On Oct 19, 2012, at 10:57 AM, Boggess, Rod wrote:****
>
>
>
> ****
>
> Is it possible to create a template on the in-built web server that would
> provide a repository-defined ReadMe.html file?****
>
> ** **
>
> I'm guessing you want to do something like BitBucket: automatically show
> the ReadMe.html on the repo's front page if it exists?****
>
> ** **
>
> *[Boggess, Rod] Awesome! Didn't know BitBucket did that. *
>
> * *
>
> *I was hoping more for a straight html page, no ReST processing and not a
> small blurb of text embedded in a <div> inside of another page, just a
> hyperlink to the ReadMe.html file. But I'm not too picky, so I'll take
> whatever the thing can do easily.*
>
**
>
> * *
>
> *Ultimately, I've been using a ReadMe.html page (with an embedded CSS
> section) to display some project details, copyright/left, and a To-Do list.
> TortoiseHg allows you to define a ReadMe file in the configuration, which
> can be displayed in the GUI's Help/ReadMe menu. Mostly, it's the ToDo list
> that's important, and I've even considered replacing the HTML/CSS with the
> b-extension's bugs file (used in this case to track todo items beyond just
> bugs), but I prefer the ability to add some polish and the additional
> project information (contacts, description, etc.).*
>
> * *
>
> *As I have it now, I can browse the files in the project repo and just
> click on the ReadMe.html file. But I don't have anything leading the other
> developers' eyes to look for the ReadMe file, and I don't have an easily
> managed TODO list. I've considered forking the b-extension to use XML for
> the data storage so that an XML-transform could be used to display HTML
> (making the todo list more manageable), but I can't get around the lack of
> affordance in displaying it. If I could add it with a template, that would
> be great! If not, -- well, I'm stuck.*
>
> * *
>

I would absolutely love to hook b into the web interface, I simply haven't
taken the time to figure out how to do that.  If you're investigating it,
I'd love to include your improvements in b.  Please don't change the data
storage model, it has to be backwards compatible.  If there's a legitimate
issue that merits using something other than b's custom plaintext, lets
talk.

Michael

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurial-scm.org/pipermail/mercurial/attachments/20121021/d57a6cea/attachment-0002.html>