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

[Rogan Hamby]

I'm not active in documenting but for what it's worth I use .adoc
extensions for SC LENDS' internal git hub materials and have taught Macs to
use it natively with TextWrangler / BBEdit.  I can't imagine it's much
harder on Windows with Notepad++.

On Fri, Jun 19, 2015 at 5:28 PM, Yamil Suarez <ysuarez at berklee.edu> wrote:

>
> 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
>
>
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>
>


-- 

Rogan Hamby, MLS, CCNP, MIA
Managers Headquarters Library and Reference Services,
York County Library System

“You can never get a cup of tea large enough or a book long enough to suit
me.”
― C.S. Lewis <http://www.goodreads.com/author/show/1069006.C_S_Lewis>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20150620/14c07eff/attachment.html>