[OPEN-ILS-DOCUMENTATION] New Docs file extension? (.asciidoc or .adoc)

[Yamil Suarez]

I am still on the fence, but I don't mind being in the minority and feel free to proceed if you guys have plurality.

Has anyone tested if the two suffixes are both converted to HTML on GitHub? (I believe someone has.) 

Has anyone "taught" their copy of Notepad or Notepad++ to automatically open these suffixes? I suspect it will be very easy to do. Though we might want to document the process on our wiki.

Yamil




> On Jun 19, 2015, at 11:55 AM, Ruth Frasur <rfrasur at gmail.com> wrote:
> 
> +1 on this.  It makes sense.  And I agree with Josh on the .adoc.
> 
>> On Fri, Jun 19, 2015 at 10:54 AM, Josh Stompro <stomproj at exchange.larl.org> wrote:
>> +1, this makes sense to me.  I think this is a good step in making the github docs workflow easier to use.  I never edit the doc files on a local computer and if I did I don’t think notepad++ would care about  the extension change.  I vote for .adoc as the extension, just because it is shorter. 
>> 
>>  
>> 
>> It helped for me to look at an example,
>> 
>> https://github.com/evergreen-library-system/Evergreen/blob/master/docs/admin/librarysettings.adoc
>> 
>> vs
>> 
>> https://github.com/evergreen-library-system/Evergreen/blob/master/docs/admin/lsa-address_alert.txt
>> 
>>  
>> 
>>  
>> 
>> Josh Stompro - LARL IT Director
>> 
>>  
>> 
>> From: OPEN-ILS-DOCUMENTATION [mailto:open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Remington Steed
>> Sent: Friday, June 19, 2015 8:35 AM
>> To: Documentation discussion for Evergreen software
>> Subject: [OPEN-ILS-DOCUMENTATION] New Docs file extension? (.asciidoc or .adoc)
>> 
>>  
>> 
>> Hi DIG,
>> 
>>  
>> 
>> At a DIG meeting on March 5th in IRC, we discussed changing all of our doc files from “NAME.txt” to “NAME.asciidoc” (or “NAME.adoc”).  The main benefit of this would be that GitHub would recognize these as AsciiDoc files and would auto-render them as HTML in the browser.  Hopefully this would make it easier for editors to check their work before submitting it.  Here is a summary of our discussion from that meeting:
>> 
>>  
>> 
>> ·         Pro: Would make editing/writing docs on GitHub more friendly
>> 
>> ·         Con: Would make editing files on local computer less friendly (if text editor doesn’t know .adoc extension, but most editors can be easily configured for this)
>> 
>> ·         Shouldn’t cause any problems with the automatic HTML conversion
>> 
>>  
>> 
>> Do you support this change?  Which extension: .asciidoc or .adoc?  Do you have any questions or concerns?  If we decide to move forward, the change could be made easily, any time, and as a single Git commit.  And we could test the nightly conversion process using the master (i.e. dev) branch before applying the change to the 2.8 and 2.7 docs.
>> 
>>  
>> 
>> Please voice your opinions!
>> 
>>  
>> 
>> Remington
>> 
>>  
>> 
>> --
>> 
>> Remington Steed
>> 
>> Electronic Resources Specialist
>> 
>> Hekman Library, Calvin College
>> 
>> http://library.calvin.edu/
>> 
>> 
>> _______________________________________________
>> OPEN-ILS-DOCUMENTATION mailing list
>> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
>> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
> 
> 
> 
> -- 
> Ruth Frasur
> 
> 
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20150619/2f6c2860/attachment.html>