[OPEN-ILS-DOCUMENTATION] Help on Documentation

Fri Oct 24 15:03:44 EDT 2014

Dananji and Josh,

Dananji, I am glad you were able to preview your changes locally. Josh
was right, his suggestion to change "image::/media" to "image:/media"
is what we needed. I am almost done pushing your (Dananji) changes to
the main repository in a few minutes.

Thanks you Josh for your research and testing skills, and thank you
Dananji for your contribution.

Have a great day,
Yamil

On Fri, Oct 24, 2014 at 2:59 PM, Dananji Liyanage <dan9131 at gmail.com> wrote:
> Hi Yamil,
>
> I checkout a branch and applied the patch, the way you have explained.
>
> I tested the patch with asciidoc, which generates an .html file with
> embedded images.
> Command: asciidoc -a data-uri -a icons MARC_RAD_MVF_CRA.txt
>
> For this I changed the way the images are called upon within the table from
> "image::media/blu-ray.png[]" to "image:../media/blu-ray.png[]"
>
> This renders all the images, other than the icon for 'Equipment, games,
> toys'. In place of the icon, it gives part of the encoding for the .png
> image. The reason for this might be, the image is corrupted.
>
>
> On Fri, Oct 24, 2014 at 11:29 PM, Dananji Liyanage <dan9131 at gmail.com>
> wrote:
>>
>> Hi Yamil,
>>
>> I tried to test the issue by making a branch from the git repo.
>>
>> Can you please tell me what do you use to get the preview of the .adoc /
>> .txt file in your local machine? I used gist in GitHub and asciidoctor
>> (Link: http://gist.asciidoctor.org/) to get the preview of my contribution.
>>
>> On Fri, Oct 24, 2014 at 3:57 AM, Yamil Suarez <ysuarez at berklee.edu> wrote:
>>>
>>> Hello,
>>>
>>> I have been working on adding Dananji's contribution that updates the
>>> search icons...
>>>
>>> https://github.com/evergreen-library-system/Evergreen/pull/34
>>>
>>> I am getting an error when trying to build the whole docs or even the
>>> one updated file. The error is related to the images she is trying to
>>> display inside some AsciiDoc tables on that updated page
>>> (docs/admin/MARC_RAD_MVF_CRA.txt).
>>>
>>> This is the error...
>>>
>>> :media/book.png: No such file or directory
>>>
>>> and this is what the AsciiDoc looks like...
>>>
>>>
>>> [width="60%", cols="<,<,<"]
>>> |====
>>> |*Icon* |*Search Label/Icon Label* |*Definition*
>>> |image::media/blu-ray.png[] | Blu ray | VR Format:s
>>> |image::media/book.png[] | All books/Book | Item Type: a,t
>>>
>>> I definitely have the images in the right place, and if I call the
>>> image from outside the table, they load up fine.
>>>
>>> Any ideas?
>>>
>>> For those that want to try it themselves, you can use this command
>>> line/Git workflow...
>>>
>>> - create a fresh branch off of master
>>>
>>> then run...
>>>
>>> wget https://github.com/evergreen-library-system/Evergreen/pull/34.patch
>>> > 34.patch
>>> git apply --check 34.patch
>>> git apply 34.patch
>>>
>>> Thanks in advance,
>>> Yamil
>>>
>>>
>>>
>>>
>>> On Mon, Oct 20, 2014 at 10:23 AM, Dananji Liyanage <dan9131 at gmail.com>
>>> wrote:
>>> > Hi Kathy,
>>> >
>>> > Thank you for the reply Kathy.
>>> >
>>> > I have made the necessary changes in a private gist I have created, but
>>> > I
>>> > didn't propose a file change yet since I don't know how to add the
>>> > images to
>>> > the /docs/media folder.
>>> >
>>> > If you can please help me on that issue, I will be able to add the
>>> > changes
>>> > to the git repo.
>>> >
>>> > On Sat, Oct 18, 2014 at 2:15 AM, Kathy Lussier <klussier at masslnc.org>
>>> > wrote:
>>> >>
>>> >> Hi Dananji!
>>> >>
>>> >> Thanks for the contribution! Overall, it looks good, but I noticed a
>>> >> couple of things.
>>> >>
>>> >> I noticed you linked directly to the icon images that are used in the
>>> >> MVLC
>>> >> catalog.  I think it would be better if you put those image files
>>> >> directly
>>> >> into the media directory of the doc repository and link to those
>>> >> instead.
>>> >> Although MVLC is using the stock images now, it's possible they could
>>> >> eventually use custom images that diverge from the ones made available
>>> >> by
>>> >> default. It's safer if the doc repository contains the images so that
>>> >> we
>>> >> have control over what we're linking to.
>>> >>
>>> >> Also, at the top of the new documentation, it says " In the table
>>> >> below
>>> >> "Icon Format Only" portions of the definition are italicized and in
>>> >> square
>>> >> brackets " However, I noticed that the information that is enclosed in
>>> >> square brackets is not italicized. I think you'll either need to
>>> >> italicize
>>> >> them or to remove the "are italicized" portion of that statement.
>>> >>
>>> >> Thanks again!
>>> >> Kathy
>>> >>
>>> >> Kathy Lussier
>>> >> Project Coordinator
>>> >> Massachusetts Library Network Cooperative
>>> >> (508) 343-0128
>>> >> klussier at masslnc.org
>>> >> Twitter: http://www.twitter.com/kmlussier
>>> >> #evergreen IRC: kmlussier
>>> >>
>>> >> On 10/16/2014 12:31 AM, Dananji Liyanage wrote:
>>> >>
>>> >> Thank you for the quick reply.
>>> >>
>>> >> I fixed the bitesize doc bug (Link:
>>> >> https://bugs.launchpad.net/evergreen/+bug/1371598) and proposed the
>>> >> file
>>> >> change ( docs/admin/MARC_RAD_MVF_CRA.txt).
>>> >>
>>> >> It would be great if you can provide feedback.
>>> >>
>>> >> On Wed, Oct 15, 2014 at 9:38 PM, Remington Steed <rjs7 at calvin.edu>
>>> >> wrote:
>>> >>>
>>> >>> Hi Dananji,
>>> >>>
>>> >>>
>>> >>>
>>> >>> I would suggest first trying to use AsciiDoc format for the table
>>> >>> data.
>>> >>> I don’t think it will be very hard to maintain.  Here is an example
>>> >>> of how
>>> >>> the syntax could look (click “Raw” to see the code):
>>> >>>
>>> >>>
>>> >>>
>>> >>> https://gist.github.com/remocrevo/98156bcca7c15353e128
>>> >>>
>>> >>>
>>> >>>
>>> >>> Remington
>>> >>>
>>> >>>
>>> >>>
>>> >>> --
>>> >>>
>>> >>> Remington Steed
>>> >>>
>>> >>> Electronic Resources Specialist
>>> >>>
>>> >>> Hekman Library, Calvin College
>>> >>>
>>> >>> http://library.calvin.edu/
>>> >>>
>>> >>>
>>> >>>
>>> >>> From: open-ils-documentation-bounces at list.georgialibraries.org
>>> >>> [mailto:open-ils-documentation-bounces at list.georgialibraries.org] On
>>> >>> Behalf
>>> >>> Of Dananji Liyanage
>>> >>> Sent: Wednesday, October 15, 2014 10:04 AM
>>> >>> To: Documentation discussion for Evergreen software
>>> >>> Subject: Re: [OPEN-ILS-DOCUMENTATION] Help on Documentation
>>> >>>
>>> >>>
>>> >>>
>>> >>> Hi Kathy,
>>> >>>
>>> >>> Thank you for the detailed reply.
>>> >>>
>>> >>> I did start on working on the bitesize doc bug (Link:
>>> >>> https://bugs.launchpad.net/evergreen/+bug/1371598), following your
>>> >>> instructions. But I'm a bit stuck at deciding what method I would
>>> >>> choose to
>>> >>> input data to the table.
>>> >>>
>>> >>> I could use a .csv file as well as write in them in AsciiDoc itself,
>>> >>> whereas the .csv file would be more feasible in making further
>>> >>> changes.
>>> >>>
>>> >>> Since I didn't come across any .csv files in the docs, I was
>>> >>> wondering
>>> >>> whether I could use that.
>>> >>>
>>> >>> It would be great if you could give your opinion on this.
>>> >>>
>>> >>>
>>> >>>
>>> >>> On Tue, Oct 14, 2014 at 9:48 PM, Kathy Lussier <klussier at masslnc.org>
>>> >>> wrote:
>>> >>>
>>> >>> Hi Dananji,
>>> >>>
>>> >>> Thank you for reaching out and for working on one of our bitesize doc
>>> >>> bugs. You might want to take a look at
>>> >>>
>>> >>> http://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:how-to-contribute-documentation
>>> >>> for some guidelines on contributing documentation. In particular, you
>>> >>> might
>>> >>> want to start with the intermediate-level instructions.
>>> >>>
>>> >>> When looking in the docs directory on GitHub
>>> >>>
>>> >>> (https://github.com/evergreen-library-system/Evergreen/tree/master/docs),
>>> >>> the directory structure closely follows the chapters of our Evergreen
>>> >>> documentation - http://docs.evergreen-ils.org/2.7/. If you can see
>>> >>> which
>>> >>> chapter your documentation lives in, then you should be able to find
>>> >>> the
>>> >>> file in the corresponding directory in the GitHub repository.
>>> >>>
>>> >>> For this project, it generally is a good idea to become familiar with
>>> >>> that directory structure and to see how the files in the repository
>>> >>> relate
>>> >>> to the HTML output you see on the Evergreen documentation site. If
>>> >>> you still
>>> >>> have trouble finding the correct file, feel free to send a follow-up
>>> >>> e-mail
>>> >>> or to drop into the #evergreen IRC channel. We usually have a lot of
>>> >>> helpful
>>> >>> people there between 9 a.m. and 4 p.m. Eastern Monday through Friday.
>>> >>> It
>>> >>> tends to be very quiet in the IRC channel during other days/times, so
>>> >>> e-mail
>>> >>> may be the best option if you're working during our off-hours.
>>> >>>
>>> >>> Kathy
>>> >>>
>>> >>> Kathy Lussier
>>> >>>
>>> >>> Project Coordinator
>>> >>>
>>> >>> Massachusetts Library Network Cooperative
>>> >>>
>>> >>> (508) 343-0128
>>> >>>
>>> >>> klussier at masslnc.org
>>> >>>
>>> >>> Twitter: http://www.twitter.com/kmlussier
>>> >>>
>>> >>> #evergreen IRC: kmlussier
>>> >>>
>>> >>> On 10/12/2014 11:54 PM, Dananji Liyanage wrote:
>>> >>>
>>> >>>
>>> >>> Hi all,
>>> >>>
>>> >>> I'm hoping to contribute
>>> >>>
>>> >>> to documentation of the Evergreen project.
>>> >>>
>>> >>> I have already decided on a bit-size bug I'm gonna work on. Can you
>>> >>> please explain me the basic steps to start, like how could I find the
>>> >>> relevant documents in GitHub?
>>> >>>
>>> >>>
>>> >>> --
>>> >>>
>>> >>> Regards,
>>> >>> Dananji Liyanage
>>> >>>
>>> >>>
>>> >>>
>>> >>> _______________________________________________
>>> >>>
>>> >>> 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
>>> >>>
>>> >>>
>>> >>>
>>> >>>
>>> >>> --
>>> >>>
>>> >>> Regards,
>>> >>> Dananji Liyanage
>>> >>>
>>> >>>
>>> >>> _______________________________________________
>>> >>> OPEN-ILS-DOCUMENTATION mailing list
>>> >>> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
>>> >>>
>>> >>> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>>> >>>
>>> >>
>>> >>
>>> >>
>>> >> --
>>> >> Regards,
>>> >> Dananji Liyanage
>>> >>
>>> >>
>>> >> _______________________________________________
>>> >> 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
>>> >>
>>> >
>>> >
>>> >
>>> > --
>>> > Regards,
>>> > Dananji Liyanage
>>> >
>>> > _______________________________________________
>>> > 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
>>> _______________________________________________
>>> OPEN-ILS-DOCUMENTATION mailing list
>>> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
>>> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>>
>>
>>
>>
>> --
>> Regards,
>> Dananji Liyanage
>
>
>
>
> --
> Regards,
> Dananji Liyanage
>
> _______________________________________________
> 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