Koha Manual in Git

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Koha Manual in Git

nengard
I have some awesome news.  As you know I'm working with both ByWater
and BibLibre.  Well thanks to BibLibre, we now have a git repo for the
Koha 3.2 Manual:
http://git.biblibre.com/cgi-bin/gitweb.cgi?p=kohadocs;a=summary -- and
I'm working on converting everything (and updating everything) over to
DocBook so that it will be much easier for translation and publishing
in multiple outlets.

What you'll see in the repo so far is a few images and the start of
the docbook file.  I am working on it daily to try and get all of the
content over.  You'll probably see me asking questions so that I can
improve on what was written so far - and fill in gaps.  Any help you
can give is greatly appreciated!!

Thank to BibLibre (and specifically Henri-Damien) for helping get this
up and running so that I can easily share my work with you all.

Thanks
Nicole C. Engard
Documentation Manager
_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Frédéric Demians
Why are you using directly DocBook format which is a nightmare to deal
with, editing, transforming? when you could use as lightweight markup
language like asciidoc?

  http://www.methods.co.nz/asciidoc/

asciidoc files can be translated to HTML and DocBook (and then PDF).
asciidoc source files can very easily be tracked  with git. Indeed git
documentation is edited with asciidoc.

Thanks for the good work by the way :-)
--
Frédéric DEMIANS
http://www.tamil.fr/u/fdemians.html
_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Chris Nighswonger
In reply to this post by nengard
On Mon, Oct 19, 2009 at 9:08 AM, Nicole Engard <[hidden email]> wrote:
I have some awesome news.  As you know I'm working with both ByWater
and BibLibre.  Well thanks to BibLibre, we now have a git repo for the
Koha 3.2 Manual:
http://git.biblibre.com/cgi-bin/gitweb.cgi?p=kohadocs;a=summary -- and
I'm working on converting everything (and updating everything) over to
DocBook so that it will be much easier for translation and publishing
in multiple outlets.

This is great news Nicole. Thanks for the continued good work!

BibLibre++ && ByWater++  #for open community contributions

Kind Regards,
Chris

_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

nengard
In reply to this post by Frédéric Demians
Because that was what was asked of me by those who work in other
languages :) No clue why I'm using it - I just do whatever I have to
to make things accessible to all.

Nicole

On Mon, Oct 19, 2009 at 9:35 AM, Frederic Demians <[hidden email]> wrote:

> Why are you using directly DocBook format which is a nightmare to deal with,
> editing, transforming? when you could use as lightweight markup language
> like asciidoc?
>
>  http://www.methods.co.nz/asciidoc/
>
> asciidoc files can be translated to HTML and DocBook (and then PDF).
> asciidoc source files can very easily be tracked  with git. Indeed git
> documentation is edited with asciidoc.
>
> Thanks for the good work by the way :-)
> --
> Frédéric DEMIANS
> http://www.tamil.fr/u/fdemians.html
>
_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Frédéric Demians

> Because that was what was asked of me by those who work in other
> languages :) No clue why I'm using it - I just do whatever I have to
> to make things accessible to all.

Speaking accessibility... This documentation:

    http://progit.org/book/

is written with asciidoc. An html version is generated (the above link).
But a PDF version can also be created from the same source files.

The source files are managed/versioned with git, and translations are
done from the English authoritative version:

    http://github.com/progit/progit

So it seems very possible to maintain a multilingual documentation with
this technique.

Now, it's only time to hope DocBook will do the job for Koha
documentation without too much overhead, even if my experience says me
the contrary.

--
Frédéric

_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

nengard
In reply to this post by nengard
I misunderstood the difference between copyright and licensing (as in
the GPL) and for that reason - and the fact that the 3.2 is so
different from 3.0 - I will be re-writing the 3.2 manual from scratch
(which will also force me to review every single section in more
detail).  For right now I'm about to update the version that is in Git
to include LibLime in the copyright tag (since it does include content
from the old 3.0/3.2 manuals).

For the future, I will be the main copyright holder on the manual and
when the Koha Foundation is formed I will sign my copyright over to
the Foundation as I don't think any one company should own the
copyright - instead it should be community owned  (feel free to keep
this email so that you have documentation of my promise).  Other
copyright holders will be ByWater Solutions and BibLibre and anyone
else who helps me write bits - or contributes their documentation for
me to include in the manual.

I hope this is acceptable to all - I think it's the best way to
support the community and the best way to force me to make sure ever
3.2 feature is accurately documented :)

Thanks everyone for your understanding and support so far,
Nicole C. Engard
Koha Documentation Manager


> from Joshua Ferraro <[hidden email]>
> to Nicole Engard <[hidden email]>
> cc [hidden email]
> date Mon, Oct 19, 2009 at 9:27 AM
> subject Re: [Koha] Koha Manual in Git
> mailed-by liblime.com

> Hi Nicole,
> As a reminder, per your employment contract 'Assignment of Inventions'
> clause, any Koha documentation content that you created during your tenure
> at LibLime is Copyright LibLime. With that in mind, be sure to reference the
> copyright holder in the main body for any content you copy over to this Git
> repository and give proper attribution for any derivative works.
> If you need a copy of the agreement you signed we'd be happy to provide you
> with one.
> Regards,
> Josh
>
> On Mon, Oct 19, 2009 at 9:08 AM, Nicole Engard <[hidden email]> wrote:
>>
>> I have some awesome news.  As you know I'm working with both ByWater
>> and BibLibre.  Well thanks to BibLibre, we now have a git repo for the
>> Koha 3.2 Manual:
>> http://git.biblibre.com/cgi-bin/gitweb.cgi?p=kohadocs;a=summary -- and
>> I'm working on converting everything (and updating everything) over to
>> DocBook so that it will be much easier for translation and publishing
>> in multiple outlets.
>>
>> What you'll see in the repo so far is a few images and the start of
>> the docbook file.  I am working on it daily to try and get all of the
>> content over.  You'll probably see me asking questions so that I can
>> improve on what was written so far - and fill in gaps.  Any help you
>> can give is greatly appreciated!!
>>
>> Thank to BibLibre (and specifically Henri-Damien) for helping get this
>> up and running so that I can easily share my work with you all.
>>
>> Thanks
>> Nicole C. Engard
>> Documentation Manager
>> _______________________________________________
>> Koha mailing list
>> [hidden email]
>> http://lists.katipo.co.nz/mailman/listinfo/koha
>
>
>
> --
> Joshua Ferraro                       SUPPORT FOR OPEN-SOURCE SOFTWARE
> CEO                         migration, training, maintenance, support
> LibLime                                Featuring Koha Open-Source ILS
> [hidden email] |Full Demos at http://liblime.com/koha |1(888)KohaILS
>
_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: [Koha-devel] Koha Manual in Git

Chris Cormack-6
2009/10/20 Nicole Engard <[hidden email]>:

> I misunderstood the difference between copyright and licensing (as in
> the GPL) and for that reason - and the fact that the 3.2 is so
> different from 3.0 - I will be re-writing the 3.2 manual from scratch
> (which will also force me to review every single section in more
> detail).  For right now I'm about to update the version that is in Git
> to include LibLime in the copyright tag (since it does include content
> from the old 3.0/3.2 manuals).
>
> For the future, I will be the main copyright holder on the manual and
> when the Koha Foundation is formed I will sign my copyright over to
> the Foundation as I don't think any one company should own the
> copyright - instead it should be community owned  (feel free to keep
> this email so that you have documentation of my promise).  Other
> copyright holders will be ByWater Solutions and BibLibre and anyone
> else who helps me write bits - or contributes their documentation for
> me to include in the manual.
>
> I hope this is acceptable to all - I think it's the best way to
> support the community and the best way to force me to make sure ever
> 3.2 feature is accurately documented :)
>
> Thanks everyone for your understanding and support so far,
> Nicole C. Engard
> Koha Documentation Manager
>
Sounds like a great plan to me,

1/ We get an updated accurate manual
2/ People don't get threatened with Lawyers

A big ++ to all your work on this Nicole, and my thanks to the people
in the community who have made it possible for you to do this

Chris
_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Thomas Dukleth-3
In reply to this post by nengard
The documentation format to use should be entirely a choice of the author
of the documentation.  However, I encourage serious consideration of the
suggestion of Frédéric Demains to use AsciiDoc.

AsciiDoc may be the easiest most accessible program to use for writing
documentation for DocBook.   AsciiDoc uses a wiki like plain text syntax
which users of a wiki would find familiar for easy contribution.  Frédéric
had not mentioned the important point that a core feature of AsciiDoc is
to output documents in DocBook format.

Using AsciiDoc may provide no actual disadvantages relative to DocBook
directly because DocBook is available as an output format.

Using AsciiDoc may provide several accessibility advantages over using
DocBook directly which may be stronger than the same accessibility reason
given for using DocBook directly.


Thomas Dukleth
Agogme
109 E 9th Street, 3D
New York, NY  10003
USA
http://www.agogme.com
+1 212-674-3783


On Mon, October 19, 2009 14:29, Nicole Engard wrote:

> Because that was what was asked of me by those who work in other
> languages :) No clue why I'm using it - I just do whatever I have to
> to make things accessible to all.
>
> Nicole
>
> On Mon, Oct 19, 2009 at 9:35 AM, Frederic Demians <[hidden email]>
> wrote:
>> Why are you using directly DocBook format which is a nightmare to deal
>> with,
>> editing, transforming? when you could use as lightweight markup language
>> like asciidoc?
>>
>>  http://www.methods.co.nz/asciidoc/
>>
>> asciidoc files can be translated to HTML and DocBook (and then PDF).
>> asciidoc source files can very easily be tracked  with git. Indeed git
>> documentation is edited with asciidoc.
>>
>> Thanks for the good work by the way :-)
>> --
>> Frédéric DEMIANS
>> http://www.tamil.fr/u/fdemians.html
>>
> _______________________________________________
> Koha mailing list
> [hidden email]
> http://lists.katipo.co.nz/mailman/listinfo/koha
>


_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Thomas Dukleth-3
[Correction from my previous message:  Frédéric Demians had mentioned
AsciiDoc translation to DocBook.]


LIST OF ADVANTAGES AND DISADVANTAGES WITH WORKAROUNDS OF ASCIIDOC IN
COMPARISON WITH USING DOCBOOK DIRECTLY.

Nicole, if the advantages seem compelling enough to you relative to any
know disadvantages, my suggestion is to try AsciiDoc for a couple of
chapters.  If in actual use AsciiDoc seems problematic, simply output your
work to DocBook and continue working in DocBook directly without having
lost anything.

Even if you have already started using DocBook directly, consider the
potential time savings of AsciiDoc in the long term.


1.  ADVANTAGES.

1.1.  USAGE EASE.

Simple wiki like syntax allows easy contributions from many who are
already familiar with some wiki syntax.  Text can be easily edited without
much worry about breaking the validation.  Anything which can reasonably
be done to make the process of contributing easy for as many people as
possible should be done.


1.2.  VALIDATION EASE.

Syntax validation checks are part of the package.  It is much easier to
avoid syntax errors in when editing in a simple text based format than in
the XML format of DocuWiki.


1.3.  VERSION CONTROL EASE.

Plain text based format with wiki like syntax allows easy version control
in Git unlike the XML format of DocBook.


1.4.  DOCBOOK OUTPUT FORMAT.

Output in multiple formats.  DocBook is the primary output format.
AsciiDoc is designed to be used for easily editing documents which will be
output into into DocBook.

XHTML and HTML are the other core output formats, however, generating
DocBook output first and then converting to other output formats gives the
best results.  Once output into DocBook, many formats are available for
final presentation.


1.5.  MACRO SUPPORT.

In addition to built in macros, custom macros can be created to allow a
simple means to create complex custom output.


1.6.  WELL RECOMMENDED.

AsciiDoc is used for editing documentation by the fine people who brought
us the wonderful version control program Git.

[I do not endorse the confrontational style which appears at the end of
the quoted message but I think that the argument is otherwise well
presented.]

From: Linus Torvalds <torvalds <at> linux-foundation.org>
Subject: Re: [ANNOUNCE] GIT 1.5.3-rc4
List: comp.version-control.git
Date: 2007-08-05 19:29:09 GMT

[...]

"I don't even bother to run "make doc".  I bet that is true of almost
everybody else too. Why? Because the *source* format we use (asciidoc) is
already basically as readable as any formatted man-page would ever be."

"You don't have to even *know* that they are AsciiDoc pages - they're just
called "*.txt", and that's what they are. Text. With very minimal fixups
that *allow* them to be used as source for things like html, and
admittedly you get prettier output, but it really is perfectly
straightforward to just read them, in ways that pretty much no other
documentation format allows. Everybody else puts very intrusive crap in
there, so that you *have* to be aware of in ways you don't need to worry
about in AsciiDoc."

"Headers? Lists? They look like headers and lists in the .txt files. No
need to think about it as a reader. "

"See? Texinfo is decidedly inferior. But you don't have to take it so
personally. So is pretty much anything else. Anything XML/SGML is even
*worse*."


1.7.  FREINDLY ORIGINS.

AsciiDoc is from New Zealand where some other software we know well was
started.


2.  DISADVANTAGES WITH WORKAROUNDS.

2.1.  DOCBOOK CONVERSION.

Converting between different formats should always be treated with some
scepticism.  Built in output conversion to DocBook may not have quite the
desired DocBook markup.  There may be a need for some DocBook elements or
degree of control which may not be supported in AsciiDoc by default.

If any output control problems are encountered, modifying the output
filters and adding custom macro controls could address them.


2.2.  WIKI MARKUP CONFUSION.

There may be a small risk that some translators might fail to recognise
the punctuation indicator for a macro and simply translate a macro
keyword.

If the boundaries between code and text might be truly unclear to some,
those people could always do translation in the DocBook output format
where the code boundaries are more clear.


2.3.  NO SUPPORT FOR UNICODE IN VARIABLES.

UTF-8 is supported in text but not in variable names used for macros.
Underscore usage may not count multi-byte characters correctly.

Avoid using anything other than ASCII text in variables as one would
expect to do on many systems.  Output to DocBook format and there should
be no need to worry about any AsciiDoc mistakes in mutli-byte character
counting.


2.4.  NO WYSIWG EDITORS.

There are no WYSIWG editors for AsciiDoc.

There should be much less need for WYSIWIG editing for AsciiDoc than with
formats more difficult for most people to read such as DocBook.  The
appearance should mostly be easily understood in an ordinary text editor.
Output to DocBook format or a final display format to when it may be
necessary to see the actual appearance as it would be represented for the
final readers.


2.5.  SECURITY PROBLEM.

Safe mode is disabled by default in the current version which prevents
checks to block the execution of malicious code inserted into a document.
There is a bug for some output to DocBook which can be triggered in safe
mode.

The security bug should be fixed in time.  Most use can be run in safe
mode without problem.  The actual hazard of malicious code being inserted
by some documentation contributor must be very small.  Precautions can be
taken to isolate any risk from unknown contributors.


2.6.  SMALL PROJECT.

AsciiDoc is a small project unlike DocBook.

AsciiDoc takes advantage of the larger DocBook project and is merely
easier to use format for editing files which will be output into DocBook
format.  Major projects like the Linux Kernel and Git are not worried
about using a small project format for documentation editing.  They are
generally quite pleased that AsciiDoc addresses their needs.


Thomas Dukleth
Agogme
109 E 9th Street, 3D
New York, NY  10003
USA
http://www.agogme.com
+1 212-674-3783

[...]


_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Frédéric Demians
Thomas, you can add that asciidoc operates very well with developers
workflow. It means it can be directly integrated in Koha git main
repository (or as submodule), and then, when a developer add a new
functionally or modify an existing one he can document it immediately,
being not intimated by DocBook schema and editing process. It works this
way in git project itself where there is no wall between developers and
technical redactors.

To get the picture, take a look at a patch like this one on git main repo:

http://tinyurl.com/yftmt2m

--
Frédéric
_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Frédéric Demians
Just to give anybody the opportunity to verify for themselves how easy
it would be to manage Koha documentation with asciidoc + git, I've set
up a git repository.

To browse it: http://git.tamil.fr/?p=kohadoc

To clone it: git clone git://git.tamil.fr/git/kohadoc

Manual source file is a plain text asciidoc file, easy to read, update
and track with git:

    * en/manual.txt
    * http://git.tamil.fr/?p=kohadoc;a=blob_plain;f=en/manual.txt;hb=HEAD

 From this source file with 'asciidoc' command (asciidoc manual.txt),
you get an html version of the documentation:

    * en/manual.html
    * http://git.tamil.fr/?p=kohadoc;a=blob_plain;f=en/manual.html;hb=HEAD

 From the same source file with "a2x -format manual.txt" command, you
get a PDF version:

    * en/manual.pdf
    * http://git.tamil.fr/?p=kohadoc;a=blob_plain;f=en/manual.pdf;hb=HEAD

--
Frédéric

_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Frédéric Demians

> From the same source file with "a2x -format manual.txt" command, you
> get a PDF version:


FIX: a2x -format pdf manual.txt

_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha
Reply | Threaded
Open this post in threaded view
|

Re: Koha Manual in Git

Thomas Dukleth-3
In reply to this post by Frédéric Demians
On first reading, I had understood Frédéric Demains' comment quoted below
without appreciating its potential effect.  In case others may have passed
over the comment with a similar mistaken appreciation, I will clarify
Frédéric's comment now that I have understood properly.

[First a simple statement clarifying my own previously given comments in
which it should still be remembered that the documentation format should
be a choice of those doing the most work on the documentation.  AsciiDoc
is merely a simple format for editing documentation for use in DocBook on
export.  AsciiDoc is not an alternative to DocBook as such.  AsciiDoc is
expressly designed to provide DocBook formatting, widely considered the
preferred base format for free software documentation.]

What Frédéric explained below gives an additional perspective on the ease
of use encourages more contributions advantage which I had given as the
first advantage for AsciiDoc in the list I had prepared of advantages and
disadvantages,
http://lists.katipo.co.nz/public/koha/2009-October/020807.html .  .

As a direct consequence of AsciiDoc using a plain text format, programmers
may be inclined to use AsciiDoc to document their work as part of the
programming process, perhaps even in the same patch.  Otherwise,
contributing to documentation is a separate process which programmers
avoid completely.  Any prospect of having the manual updated by those
writing the programming code as their patches are applied to the code in
one step is very significant advantage.

Programmer changes to the manual as might be needed parallel to a code
change would apply to the version of the manual corresponding to the
version of the software in which the code change would be introduced.  If
even one programmer could be encouraged to document his work just a little
as he coded it, there would be much less time spent identifying how things
work in the first place for the manual.

Less time of the documentation manager and others would be needed
identifying what needs to be described in the manual.  More time could be
available for ensuring that the description is clear for all users and
other good purposes.

Using the DocBook format directly should not stop programmers from
updating the manual, although, it might preclude updates to the manual in
the same patch and would require a greater effort.  In reality, any
documentation editing format which requires much expenditure of time on
the part of programmers would only increase the prevalent tendency of
programmers not to document their own work.

Programmers need any encouragement which may be obtained to better
appreciate the importance of including comments in the code which they
write, especially for the benefit other programmers.  They also need any
possible encouragement to document their own work for everyone.


Thomas Dukleth
Agogme
109 E 9th Street, 3D
New York, NY  10003
USA
http://www.agogme.com
+1 212-674-3783


On Tue, October 20, 2009 20:32, Frederic Demians wrote:

> Thomas, you can add that asciidoc operates very well with developers
> workflow. It means it can be directly integrated in Koha git main
> repository (or as submodule), and then, when a developer add a new
> functionally or modify an existing one he can document it immediately,
> being not intimated by DocBook schema and editing process. It works this
> way in git project itself where there is no wall between developers and
> technical redactors.
>
> To get the picture, take a look at a patch like this one on git main repo:
>
> http://tinyurl.com/yftmt2m
>
> --
> Frédéric
>
>

_______________________________________________
Koha mailing list
[hidden email]
http://lists.katipo.co.nz/mailman/listinfo/koha