On 2014-08-28 11:42-0700 David MacMahon wrote: > Hi, Alan, > > On Aug 28, 2014, at 10:46 AM, Alan W. Irwin wrote: > >> On 2014-08-28 12:44-0400 Hazen Babcock wrote: >> >>> In the README file, should I be able to click on the links when viewed here? >>> http://sourceforge.net/p/plplot/plplot/ci/master/tree/ >> >> I don't think that is possible with plain text (which we want this >> file to be for the case when this README file is included, say, in a >> tarball). > > FWIW, Markdown is a very nearly plain text file format that is often used for > README files (e.g. on github). I see in the link you provided that > sourceforge supports Markdown, but only for README files with a markdown-like > extension. If you would like the URLs in the README files to be links on the > sourceforge repository browsing page (an possibly other places?), then it > sounds like you could rename them to README.md (and README.developers.md > etc). This might necessitate some reformatting if some previous plain text > formatting gets mis-interpreted as unwanted markdown formatting. > > The Markdown syntax is very non-intrusive to a human reader. To humans, > markdown files read very much like well formatted plain text files so they > are well suited for inclusion in tarballs. >
Hi Dave: Thanks for reminding me of markdown which I must have encountered before because I certainly like the angle bracket syntax for URL's. I think it would be a good idea to convert our README files to markdown syntax whenever the opportunity/time was available. Actually, I have already unknowingly started doing that by using the angle-bracket syntax for URL's in the top-level README. But obviously that is not enough since the links are not clickable despite the statement at <http://sourceforge.net/p/forge/documentation/markdown_syntax/> that "SourceForge uses markdown syntax everywhere to allow you to create rich text markup [....]" According to http://sourceforge.net/p/forge/documentation/Files-Readme/ it may be that all I would have to do was change the README name to README.md to make the SF software translate that file from markdown to html, but then according to that same documention we would not be in a good situation because any other file in the same directory with readme or README somewhere in the name would take precedence if updated later than README.md. That precedence issue is not much of a concern for the file release area where you typically upload some README file after uploading the tarball. But for the git browsing area precedence would be a concern for a number of our source code directories. Anyhow, the Allura software that runs SourceForge may not have rules in place to deal with the file precedence issue for the git browsing case, or there may be special rules in that case (such as the one I just discovered where README has precedence over all other name forms). For now I think it is a good idea to encourage markdown syntax in README files, but I suggest we leave the filename as is and hope SF figures out they should apply the markdown transformation in the case where README files have markdown syntax or else figures out the precedence issue if the markdown format can be recognized by Allura only if there is a special filename suffix such as ".md". Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ Slashdot TV. Video for Nerds. Stuff that matters. http://tv.slashdot.org/ _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
