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

[Yamil Suarez]

Thanks for the confirmation Rogan, and for sharing your success with
the suffix within Github.

Yamil



On Sat, Jun 20, 2015 at 8:06 PM, Rogan Hamby <rogan.hamby at yclibrary.net> wrote:
> 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
>
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>



-- 



--------------------------------

Yamil Suarez, MCS
Library System Administrator/Developer

Stan Getz Library
Berklee College of Music
1140 Boylston St
Boston, MA 02215

ysuarez at berklee.edu
617-747-2617