Re: [Koha-devel] 3.8.4 interim [was: koha-zebra-daemon not starting]
At 04:41 PM 8/22/2012 -0300, Tomas Cohen Arazi wrote: [snip]
The tarball has always worked extremely well on i386 machines -- I just get the impression (not proven) that Ubuntu 12.04 gets its knickers in a twist on AMD64. Â But with a little time and effort workarounds can be found. Â Probably nothing wrong, just new quirks, with either Ubuntu or Koha, but I do not need to be under pressure for the production upgrade.
is not a 12.04 problem, is a problem with the specific file you're using with dpkg, which lists some files not available anymore on 12.04. As Mark said that file has already been patched and its waiting for inclusion on next release.
Thanks for the reply. But, as you say, "its waiting for inclusion on next release" so it's broken in this release.
That said, you can do a clean install using the instructions and ommiting that --set-selections step. And installing the dependencies by hand. As Mark also said.
More or less what I've done -- but it would not be rocket science to edit install_misc/ubuntu.packages to avoid a certain amount of grief (and before anyone asks "well why don't you do it?" I will as soon as I'm certain that my experience is reproducible and bullet-proof. It may involve looking at the upstream .pl file to see how the list is invoked.)
I also use the tarball in our deployment (38 instances on a single BIG server) without issues.
I'm only trying a test install on relatively BIG server (64-bit, 6 core Intel i7-980X, solid state raided drives, 16Gb ram), mileage varies...
Besides that i386 packages pull which I reported and has been solved.
When, where, how? I had to 'sudo apt-get purge .*:i386' for about 50 dependencies in the pull in koha-3.08.04.tar.gz
Anyway, I think we should go back to what your original problem was. Is your incremental indexing working?
That was 3.8.3, now trashed, but it never worked -- I'll try it on a 3.8.4 install as soon as I'm away from this machine.
Have you properly set your sax parser? [snip]
Yes. Best - P. --- Maritime heritage and history, preservation and conservation, research and education through the written word and the arts. <http://NavalMarineArchive.com> and <http://UltraMarine.ca>
Paul, You're right. The current stable tarball includes: - Outdated INSTALL.ubuntu* files - Outdated misc/ubuntu.packages file All people that answered your questions is aware of that (we meet at IRC every day and have nice exchanges on that subject). We even fixed that problem, and it should be in future releaes soon (our workflow is not optimal sometimes, there have been more urgent issues to fix). What we're all saying is that you are right about that; and besides that, Koha runs flawlessly for of us on 64 bit servers, runnning on Ubuntu LTS distro (12.04 and 10.04). People just told you how to circumvent those issues. Regards To+ PS: Sorry for my poor english. PS2: I've struggled and got annoyed for the outdated docs, and even filled this http://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=8478. You'll see Mark's work there.
Regards To+
PS: Sorry for my poor english.
PS2: I've struggled and got annoyed for the outdated docs, and even filled this http://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=8478. You'll see Mark's work there.
Tomas there has been some discussion about ways to improve the Koha install docs the big problem is... there are too many 'Koha installation guides' on the kc.org wiki that have old ,incorrect, redundant or duplicated info i think we need to remove the duplicated installation documentation from the wiki and concentrate on improving the INSTALL.* files in the Koha git repository (just like we do with the Koha user-manual) lets have a single place for the Koha installation files (and a consistent format) lets have modifications to those critical and complex files go-thru a QA process and version control, too many people google-search for 'koha installation help guide', then find these incorrect guides and have horrible experiences installing Koha :/ what do other Koha devs think? does anyone else agree that these old or inaccurate install guides are causing problems for Koha newbies? Mason
On 23 August 2012 12:25, Mason James <mtj@kohaaloha.com> wrote:
Regards To+
PS: Sorry for my poor english.
PS2: I've struggled and got annoyed for the outdated docs, and even filled this http://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=8478. You'll see Mark's work there.
Tomas
there has been some discussion about ways to improve the Koha install docs
the big problem is... there are too many 'Koha installation guides' on the kc.org wiki that have old ,incorrect, redundant or duplicated info
i think we need to remove the duplicated installation documentation from the wiki and concentrate on improving the INSTALL.* files in the Koha git repository (just like we do with the Koha user-manual)
lets have a single place for the Koha installation files (and a consistent format)
lets have modifications to those critical and complex files go-thru a QA process and version control, too
many people google-search for 'koha installation help guide', then find these incorrect guides and have horrible experiences installing Koha :/
what do other Koha devs think? does anyone else agree that these old or inaccurate install guides are causing problems for Koha newbies?
+1 for bringing them into version control and under signoff/qa process. Chris
On Wed, Aug 22, 2012 at 9:01 PM, Chris Cormack <chris@bigballofwax.co.nz>wrote:
what do other Koha devs think? does anyone else agree that these old or inaccurate install guides are causing problems for Koha newbies?
+1 for bringing them into version control and under signoff/qa process.
If we follow through with this, it would be trivial to write up a script to pull the various *.INSTALL files from the repo and transform them into wiki pages. This could be cron'd up so the wiki pages always matched the files in the repo. Kind Regards, Chris
On 23 August 2012 13:52, Chris Nighswonger <cnighswonger@foundations.edu> wrote:
On Wed, Aug 22, 2012 at 9:01 PM, Chris Cormack <chris@bigballofwax.co.nz> wrote:
what do other Koha devs think? does anyone else agree that these old or inaccurate install guides are causing problems for Koha newbies?
+1 for bringing them into version control and under signoff/qa process.
If we follow through with this, it would be trivial to write up a script to pull the various *.INSTALL files from the repo and transform them into wiki pages. This could be cron'd up so the wiki pages always matched the files in the repo.
+1 for this idea also Chris
Salvete!
the big problem is... there are too many 'Koha installation guides' on the kc.org wiki that have old ,incorrect, redundant or duplicated info
Alternatively, we could mark those entries up with wiki tags to reflect that there is old, incorrect, or redundant redundant redundant information. :) Then we can have some folks that aren't eyeball deep in code go and fix 'em. Cheers, Brooke
Greetings, Yes, I was hoping to getting around to cleaning up the documentation further. However until I have a 64-bit OS to attempt to install, I can't really address all the problems some people are encountering. Which bugs me, because I want good documentation for all three types of installs. The problem is you can't write step-by-step documentation for each OS, because a tarball install under Debian, Ubuntu, CentOS are all going to encounter different problems. Similarly, a git install will as well. You can only write "here's a problem you may encounter and here's an example of how to handle it". This gets compounded into a people looking for a step-by-step guide, and they'll keep hunting until they find one regardless of how dated it is. I believe the http://wiki.koha-community.org/wiki/Koha_on_Ubuntu is a good place for a basic set of tarball instructions. The problem then becomes OS specific when trying to install dependencies like http://wiki.koha-community.org/wiki/Koha_3.6_on_Centos_6.2_i386. This is another reason packages is a better way: the dependencies should all be there. GPML, Mark Tompsett
I agree with all of you. And must add that a while ago I started the rewrite of the Ubuntu install files (look at the first commit on that bug), after which Mark put his hands on it and now we've got this fresh install instructions. For that purpose I set (on our infrastructure) both a 10.04 and 12.04 Ubuntu Server setups to test and QA those install instructions. Both are 64bit, hence when I signed-off on those instructions, I meant to say I fully tested them to work for amd64 arch. INSTALL files where way too old, and that made them difficult to maintain. If what we need is volunteers, I already volunteered for Ubuntu files. Regards To+ On Thu, Aug 23, 2012 at 1:12 AM, Mark Tompsett <mtompset@hotmail.com> wrote:
Greetings,
Yes, I was hoping to getting around to cleaning up the documentation further. However until I have a 64-bit OS to attempt to install, I can't really address all the problems some people are encountering. Which bugs me, because I want good documentation for all three types of installs.
The problem is you can't write step-by-step documentation for each OS, because a tarball install under Debian, Ubuntu, CentOS are all going to encounter different problems. Similarly, a git install will as well. You can only write "here's a problem you may encounter and here's an example of how to handle it". This gets compounded into a people looking for a step-by-step guide, and they'll keep hunting until they find one regardless of how dated it is.
I believe the http://wiki.koha-community.org/wiki/Koha_on_Ubuntu is a good place for a basic set of tarball instructions. The problem then becomes OS specific when trying to install dependencies like http://wiki.koha-community.org/wiki/Koha_3.6_on_Centos_6.2_i386. This is another reason packages is a better way: the dependencies should all be there.
GPML, Mark Tompsett
On 2012-08-24, at 2:02 AM, Tomas Cohen Arazi wrote:
I agree with all of you. And must add that a while ago I started the rewrite of the Ubuntu install files (look at the first commit on that bug), after which Mark put his hands on it and now we've got this fresh install instructions.
For that purpose I set (on our infrastructure) both a 10.04 and 12.04 Ubuntu Server setups to test and QA those install instructions. Both are 64bit, hence when I signed-off on those instructions, I meant to say I fully tested them to work for amd64 arch.
INSTALL files where way too old, and that made them difficult to maintain. If what we need is volunteers,
I already volunteered for Ubuntu files.
awesome Tomaz i'll volunteer to update and do QA on the debian INSTALL.* files anyone wanna volunteer for any other distros? (fedora, centos, etc…)
On Thu, Aug 23, 2012 at 10:49 AM, Mason James <mtj@kohaaloha.com> wrote:
I already volunteered for Ubuntu files.
awesome Tomaz
i'll volunteer to update and do QA on the debian INSTALL.* files
If we can agree to some sort of standardized formatting, I'll write a parser to generate the wiki pages from the INSTALL files. Kind Regards, Chris
Op 23-08-12 17:14, Chris Nighswonger schreef:
If we can agree to some sort of standardized formatting, I'll write a parser to generate the wiki pages from the INSTALL files.
Wiki formatting would make sense, wouldn't it? It's reasonably readable too. -- Robin Sheat Catalyst IT Ltd. ✆ +64 4 803 2204 GPG: 5957 6D23 8B16 EFAB FEF8 7175 14D3 6485 A99C EB6D
On Thu, Aug 23, 2012 at 11:17 AM, Robin Sheat <robin@catalyst.net.nz> wrote:
Op 23-08-12 17:14, Chris Nighswonger schreef:
If we can agree to some sort of standardized formatting, I'll write a parser to generate the wiki pages from the INSTALL files.
Wiki formatting would make sense, wouldn't it?
I was hoping someone would suggest that... ;-)
It's reasonably readable too.
For the most part We could to them in POD and then do something like pod2wiki: http://search.cpan.org/~jmcnamara/Pod-Simple-Wiki-0.14/bin/pod2wiki Which would allow such as 'perldoc INSTALL.foo' and such. Kind Regards, Chris
On 2012-08-24, at 3:25 AM, Chris Nighswonger wrote:
On Thu, Aug 23, 2012 at 11:17 AM, Robin Sheat <robin@catalyst.net.nz> wrote: Op 23-08-12 17:14, Chris Nighswonger schreef:
If we can agree to some sort of standardized formatting, I'll write a parser to generate the wiki pages from the INSTALL files.
Wiki formatting would make sense, wouldn't it?
I was hoping someone would suggest that... ;-)
It's reasonably readable too.
For the most part
We could to them in POD and then do something like pod2wiki: http://search.cpan.org/~jmcnamara/Pod-Simple-Wiki-0.14/bin/pod2wiki
Which would allow such as 'perldoc INSTALL.foo' and such.
yep, thats the idea Chris :) there looks to be some good conversion tools between asciidoc, pod, and wiki (and then html, docbook, pdf and latex too) some conversion tools are going to work better that others. and some probably won't work at all i'll attempt to do some 'conversion testing' to see what the best/worst formats are https://github.com/giftnuss/p5-pod-asciidoc http://stackoverflow.com/questions/7612374/how-to-convert-asciidoc-to-perl-p... http://search.cpan.org/~dagolden/Pod-WikiDoc/ https://github.com/agentzh/nginx-devel-utils/blob/master/wiki2pod.pl http://search.cpan.org/~jmcnamara/Pod-Simple-Wiki-0.14/bin/pod2wiki http://code.google.com/p/mastermind-strategy/source/browse/wiki/wiki2pod?spec=svn198&r=198
Op 23-08-12 21:00, Mason James schreef:
there looks to be some good conversion tools between asciidoc, pod, and wiki (and then html, docbook, pdf and latex too)
While you're exploring, I hear good things about markdown as a human-writable but still parseable format, and I'd give good odds there's a markdown to mediawiki converter. -- Robin Sheat Catalyst IT Ltd. ✆ +64 4 803 2204 GPG: 5957 6D23 8B16 EFAB FEF8 7175 14D3 6485 A99C EB6D
On 2012-08-24, at 7:27 AM, Robin Sheat wrote:
Op 23-08-12 21:00, Mason James schreef:
there looks to be some good conversion tools between asciidoc, pod, and wiki (and then html, docbook, pdf and latex too)
While you're exploring, I hear good things about markdown as a human-writable but still parseable format, and I'd give good odds there's a markdown to mediawiki converter.
i've just discovered the 'pandoc' tool, which looks like it does every conversion possible :) http://johnmacfarlane.net/pandoc/ http://packages.debian.org/squeeze/pandoc i'll get some tests sorted this week, for the various doc formats. stay tuned…
On 2012-08-28, at 8:18 AM, Mason James wrote:
On 2012-08-24, at 7:27 AM, Robin Sheat wrote:
Op 23-08-12 21:00, Mason James schreef:
there looks to be some good conversion tools between asciidoc, pod, and wiki (and then html, docbook, pdf and latex too)
While you're exploring, I hear good things about markdown as a human-writable but still parseable format, and I'd give good odds there's a markdown to mediawiki converter.
i've just discovered the 'pandoc' tool, which looks like it does every conversion possible :)
http://johnmacfarlane.net/pandoc/ http://packages.debian.org/squeeze/pandoc
i'll get some tests sorted this week, for the various doc formats.
stay tuned…
ok, so a little late... but some very successful news… :) I've managed to sort some *automated* steps to convert the installation-docs on kc.org wiki, to many various doc formats... i spent some time experimenting with the big 3 formats - RST, markdown and asciidoc (all 3 were very nice, cheers!) after a process of elimination, RST was a pretty clear winner, why? 1/ asciidoc has some import problems with pandoc (i.e.: its not currently supported) 2/ RST integrates tightly with sphinx, so HTML generated with RST is prettier than markdown as examples, i've converted 2 docs from the kc.org wiki to RST so these 2 wiki docs... http://wiki.koha-community.org/wiki/Debian http://wiki.koha-community.org/wiki/Koha_on_Ubuntu convert to these 2 RST docs... http://pub.kohaaloha.com/kohadocs-sphinx/debian.html http://pub.kohaaloha.com/kohadocs-sphinx/ubuntu.html then, using RST and pandoc, we can convert the docs to almost any format needed (take a look at all those output formats :) -> http://johnmacfarlane.net/pandoc/ ) as a nice bonus with RST, we also get to convert the Koha manual (docbook/xml) to RST/sphinx too so, from this... http://manual.koha-community.org/3.10/en/administration.html to this... http://pub.kohaaloha.com/kohadocs-sphinx/man.html finally... I'm volunteering to be Koha's 'installation doumentation' manager a new role, similar to Nicole's 'documentation manager' role, but focusing on Koha's installation documentation only http://en.wikipedia.org/wiki/ReStructuredText http://en.wikipedia.org/wiki/Markdown http://en.wikipedia.org/wiki/Asciidoc http://sphinx.pocoo.org/contents.html
Greetings, [snip]
finally... I'm volunteering to be Koha's 'installation doumentation' manager a new role, similar to Nicole's 'documentation manager' role, but focusing on Koha's installation documentation only
+1 I think this role is necessary so that installation documentation can be consistent and be subject to a Q/A process which is guided by the "Installation Documentation Manager". GPML, Mark Tompsett
Le 10/09/2012 06:18, Mason James a écrit :
after a process of elimination, RST was a pretty clear winner, why? Hi Mason,
I'm not sure I understand well what you're proposing here : write the install doc in RST ? rewrite all the doc (including Nicole one) ? Thx for clarifying my cloudy brain ;-)
finally... I'm volunteering to be Koha's 'installation doumentation' manager a new role, similar to Nicole's 'documentation manager' role, but focusing on Koha's installation documentation only +100 !
-- Paul POULAIN http://www.biblibre.com Expert en Logiciels Libres pour l'info-doc Tel : (33) 4 91 81 35 08
On 2012-09-10, at 8:00 PM, Paul Poulain wrote:
Le 10/09/2012 06:18, Mason James a écrit :
after a process of elimination, RST was a pretty clear winner, why? Hi Mason,
I'm not sure I understand well what you're proposing here : write the install doc in RST ?
yep, basically thats it :) 1/ move all the current and correct install doco to a git repo, (converted to .RST) 2/ mark old/obsolete doco as *WARNING - DEPRECIATED*, and redirect to new doco location (...or just delete the old doco)++ then, later, consolidate the install-doco into some general files much of the installation steps are similar for all OS's - lets try to reduce duplication
rewrite all the doc (including Nicole one) ?
no - i just show that its easy to convert the Koha manual to RST its Nicole's decision, if she wants to do that :)
Salvete!
(...or just delete the old doco)++
Don't pick this option. Warn instead. (http://en.wikipedia.org/wiki/Category:User_warning_templates) As someone with deprecated documentation, on the few occasions when I return to clean things up, I count on my old doc being there as a starting point. Old documentation serves a historical purpose, too. I just read an academic article that cited work from 2003 for our project. Granted, that wasn't installation documentation, but it was good to see something from that long ago in the paper. It's useful to have archival versions of Koha and archival versions of the documentation so that folks can get a grasp of the progress that's been made. That said, there should definitely be warnings that folks are taking a trip down memory lane, and they should be redirected to the new versions. The most important reason to keep it round is that folks still use it, in especial people that are too hard pressed for cash to upgrade. Believe me, I die a little inside when someone contacts me at my school address, since I know that they're using one of the oldest forms of my Newbie Guide, but it happens with regularity. I of course redirect them to newer documentation. I'd like for people to install the newest shiniest version of Koha on the newest shiniest version of Debian, but unfortunately this just isn't the way a lot of people operate. Cheers, Brooke
Hi, On Mon, Sep 10, 2012 at 7:23 AM, BWS Johnson <abesottedphoenix@yahoo.com> wrote:
Salvete!
(...or just delete the old doco)++
Don't pick this option. Warn instead. (http://en.wikipedia.org/wiki/Category:User_warning_templates)
+1 Regards, Galen -- Galen Charlton Director of Implementation Equinox Software, Inc. / The Open Source Experts email: gmc@esilibrary.com direct: +1 770-709-5581 cell: +1 404-984-4366 skype: gmcharlt web: http://www.esilibrary.com/ Supporting Koha and Evergreen: http://koha-community.org & http://evergreen-ils.org
On 2012-09-11, at 1:13 AM, Galen Charlton wrote:
Hi,
On Mon, Sep 10, 2012 at 7:23 AM, BWS Johnson <abesottedphoenix@yahoo.com> wrote:
Salvete!
(...or just delete the old doco)++
Don't pick this option. Warn instead. (http://en.wikipedia.org/wiki/Category:User_warning_templates)
+1
Regards,
Galen
ok, I'm happy with this, too :) I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1 i'll ask someone the enable the 'mbox' templates on wiki.kc.org
Mason James schrieb am 13.09.2012 09:51:11
I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1
I like it. I would not mind a larger symbol (2-3x the size). -- Mirko
On 2012-09-13, at 7:54 PM, Mirko wrote:
Mason James schrieb am 13.09.2012 09:51:11
I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1
I like it. I would not mind a larger symbol (2-3x the size).
yes, thats possible too the other 'enhancement' is to repeat the warning through the document, just in case someone missing the warning at the top of the page ;) thanks for your suggestion
On 2012-09-14, at 2:43 PM, Mason James wrote:
On 2012-09-13, at 7:54 PM, Mirko wrote:
Mason James schrieb am 13.09.2012 09:51:11
I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1
I like it. I would not mind a larger symbol (2-3x the size).
yes, thats possible too
fyi: its exactly the same symbol (and size) as on wikipedia.org http://www.mediawiki.org/wiki/Template:Mbox so, if it works OK for wiki.org, it probably works OK for us
Greetings, Mason James initially wrote:
I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1
Mirko wrote:
I like it. I would not mind a larger symbol (2-3x the size).
Mason James replied:
yes, thats possible too
the other 'enhancement' is to repeat the warning through the document, just in case someone missing the warning at the top of the page ;)
Is it possible to water mark the warning symbol? So no matter where they scroll, the background has the large warning symbol subtly showing through the text at them? Make sure the contrast makes it hard to read. ;) I believe in the power of the user to ignore warnings, and only annoying repetition and disjointedness is going to force them to stop doing it the wrong way. GPML, Mark Tompsett
On 2012-09-14, at 10:54 PM, Mark Tompsett wrote:
Greetings,
Mason James initially wrote:
I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1
Mirko wrote:
I like it. I would not mind a larger symbol (2-3x the size).
Mason James replied:
yes, thats possible too
the other 'enhancement' is to repeat the warning through the document, just in case someone missing the warning at the top of the page ;)
Is it possible to water mark the warning symbol? So no matter where they scroll, the background has the large warning symbol subtly showing through the text at them? Make sure the contrast makes it hard to read. ;)
i really like the idea but i don't know how to do that within mediawiki :/ if you work out a way to do it, then great - patches welcome!
At 02:43 PM 9/14/2012 +1200, Mason James wrote:
On 2012-09-13, at 7:54 PM, Mirko wrote:
Mason James schrieb am 13.09.2012 09:51:11
I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1 I like it. I would not mind a larger symbol (2-3x the size).
yes, thats possible too
Current size "imitates" mainstream Wiki warnings. Is it necessary to reinvent the wheel? Best - P.
Greetings,
Current size "imitates" mainstream Wiki warnings. Is it necessary to reinvent the wheel?
Yes, because some people don't listen to recommendations. They just want to install (etc.) and not have to understand and figure out the right way to do it. GPML, Mark Tompsett
On 2012-09-15, at 1:14 AM, Paul wrote:
At 02:43 PM 9/14/2012 +1200, Mason James wrote:
On 2012-09-13, at 7:54 PM, Mirko wrote:
Mason James schrieb am 13.09.2012 09:51:11
I've sorted out an example 'obsolete' style warning, http://pub2.kohaaloha.com/mediawiki/index.php/X1 I like it. I would not mind a larger symbol (2-3x the size).
yes, thats possible too
Current size "imitates" mainstream Wiki warnings. Is it necessary to reinvent the wheel?
if people want a bigger symbol, I'm fine with that - its a one line change currently theres 2 vote for a bigger symbol, and 1 vote for a normal symbol so, at the mo, big symbol it is… ;)
Greetings, [snip] Re: proposal for use of a standard for documentation (RST) -- Don't care about the format. But I like standards. Standards clarify and guide. Standards are good. [snip]
2/ mark old/obsolete doco as *WARNING - DEPRECIATED*, and redirect to new doco location (...or just delete the old doco)++
I think this would depend on how popular the page is. Is there a way of knowing if the page has even been viewed in the last X months? Do we really need pages that are... 2 years old without access? I think a deletion in those cases is reasonable. However, if it was accessed in the last few months, then a redirect is preferred over a warning, because people ignore warnings all the time. However, in the case of historically accurate and useful pages, a warning is a good idea. I like the sample warning you gave, but it is too small. People need to be told in full screen boldness it is outdated, otherwise they will in advertently miss it. If people wish to ignore full screen warnings, then there's not much we can do short of a delete. Not to mention. If the information is still in RST format on the repo, no data is really lost, and it is available for the advanced user. GPML, Mark Tompsett
On 2012-09-13, at 2:30 PM, Mark Tompsett wrote:
Greetings,
[snip] Re: proposal for use of a standard for documentation (RST) -- Don't care about the format. But I like standards. Standards clarify and guide. Standards are good.
[snip]
2/ mark old/obsolete doco as *WARNING - DEPRECIATED*, and redirect to new doco location (...or just delete the old doco)++
I think this would depend on how popular the page is. Is there a way of knowing if the page has even been viewed in the last X months?
nope, there is no way to do that so, your following suggestion are a no-go
Do we really need pages that are... 2 years old without access? I think a deletion in those cases is reasonable.
However, if it was accessed in the last few months, then a redirect is preferred over a warning, because people ignore warnings all the time.
However, in the case of historically accurate and useful pages, a warning is a good idea. I like the sample warning you gave, but it is too small. People need to be told in full screen boldness it is outdated, otherwise they will in advertently miss it. If people wish to ignore full screen warnings, then there's not much we can do short of a delete.
Not to mention. If the information is still in RST format on the repo, no data is really lost, and it is available for the advanced user.
At 03:00 PM 9/14/2012 +1200, Mason James wrote:
On 2012-09-13, at 2:30 PM, Mark Tompsett wrote:
Greetings, [snip] Re: proposal for use of a standard for documentation (RST) -- Don't care about the format. But I like standards. Standards clarify and guide. Standards are good.
+1 for the "like standards." However, I've never worked with R[e]ST, so have one question which I believe is technically possible. Given that Koha "should" be installed on a server version of the library's chosen OS, there is by most definitions no web browser available; will the RST be made available as text (in the tarball/package) to allow copy/paste of cli lines using vi (or whatever) during the install process? Thanks - Paul
Greetings,
will the RST be made available as text [snip] to allow copy/paste of cli lines using vi (or whatever) during the install process?
The tarball will have Git installation method instructions for Ubuntu. After all, if you are doing a packages installation, you will not have an INSTALL.ubuntu file on the machine. The Wiki will have Packages and Git installation method instructions for Ubuntu. Packages for production and testing environments, git for developers in testing and development environment. The RSTs will be hidden away from the general populous in a git repository, and conversions from the RST to Wiki or INSTALL.{OS} files will be made in a human readable format. This is one reason the RST format was chosen. It converts well to many different formats. In a git repository, patches can be submitted against it to the Installation Documentation Manager. The details of that process have yet to be worked out exactly. But it will likely be similar to what is done for Koha Documentation in general. And no, the tarball instructions won't be deleted, they'll be hidden in that git repository. And if someone is able to figure out how to get to the git repository, perhaps they've learned enough to do a packages or git installation. Tarball instructions have not been necessary for debian-based OSes since Koha 3.4. Package installations were available as early as 3.0. Though pushes to use that methodology were not made until version 3.4.
Given that Koha "should" be installed on a server version of the library's chosen OS
Uh... No. The recommendation for OS is: Debian. My understanding is a netinstall is a good no-desktop-environment setup for Debian. Ubuntu has a Server edition, but I haven't seen such a beast for Debian. Other debian-based OSes work, but are not the recommendation. Also, support may be limited as the majority of developers for Koha are under Debian. It's hard to support Redhat based OSes when you only have a Debian box. Though, people have gotten Koha to work on non-debian based OSes. I even tinkered with getting it to work on CentOS 6.3, but that isn't Debian. Ubuntu is a debian-based OS and can run Koha well, but Debian is the recommendation. I understand that organizational constraints may require the use of a particular OS, but Debian is the preferred OS. And I will admit to using Ubuntu, but it is not the recommended Debian. I feel like Steve Ballmer, except instead of developers, I'm saying Debian.
there is by most definitions no web browser available
lynx is a web browser and works perfectly well for doing the web install. I wouldn't recommend it for anything past that though. GPML, Mark Tompsett P.S. Did I get any details not quite right, mtj? (http://wiki.koha-community.org/wiki/Roles_for_3.12)
On 2012-09-15, at 3:35 AM, Mark Tompsett wrote:
Greetings,
will the RST be made available as text [snip] to allow copy/paste of cli lines using vi (or whatever) during the install process?
The tarball will have Git installation method instructions for Ubuntu. After all, if you are doing a packages installation, you will not have an INSTALL.ubuntu file on the machine. The Wiki will have Packages and Git installation method instructions for Ubuntu. Packages for production and testing environments, git for developers in testing and development environment.
The RSTs will be hidden away from the general populous in a git repository, and conversions from the RST to Wiki or INSTALL.{OS} files will be made in a human readable format. This is one reason the RST format was chosen. It converts well to many different formats.
In a git repository, patches can be submitted against it to the Installation Documentation Manager. The details of that process have yet to be worked out exactly. But it will likely be similar to what is done for Koha Documentation in general.
And no, the tarball instructions won't be deleted, they'll be hidden in that git repository. And if someone is able to figure out how to get to the git repository, perhaps they've learned enough to do a packages or git installation. Tarball instructions have not been necessary for debian-based OSes since Koha 3.4. Package installations were available as early as 3.0. Though pushes to use that methodology were not made until version 3.4.
Given that Koha "should" be installed on a server version of the library's chosen OS
Uh... No. The recommendation for OS is: Debian. My understanding is a netinstall is a good no-desktop-environment setup for Debian. Ubuntu has a Server edition, but I haven't seen such a beast for Debian. Other debian-based OSes work, but are not the recommendation. Also, support may be limited as the majority of developers for Koha are under Debian. It's hard to support Redhat based OSes when you only have a Debian box. Though, people have gotten Koha to work on non-debian based OSes. I even tinkered with getting it to work on CentOS 6.3, but that isn't Debian. Ubuntu is a debian-based OS and can run Koha well, but Debian is the recommendation. I understand that organizational constraints may require the use of a particular OS, but Debian is the preferred OS. And I will admit to using Ubuntu, but it is not the recommended Debian. I feel like Steve Ballmer, except instead of developers, I'm saying Debian.
there is by most definitions no web browser available
lynx is a web browser and works perfectly well for doing the web install. I wouldn't recommend it for anything past that though.
GPML, Mark Tompsett
P.S. Did I get any details not quite right, mtj? (http://wiki.koha-community.org/wiki/Roles_for_3.12)
well, you've given a bunch of info and opinion completely unrelated to Paul's question but other than that… its perfect!
On 2012-09-15, at 1:22 AM, Paul wrote:
At 03:00 PM 9/14/2012 +1200, Mason James wrote:
On 2012-09-13, at 2:30 PM, Mark Tompsett wrote:
Greetings, [snip] Re: proposal for use of a standard for documentation (RST) -- Don't care about the format. But I like standards. Standards clarify and guide. Standards are good.
+1 for the "like standards." However, I've never worked with R[e]ST, so have one question which I believe is technically possible. Given that Koha "should" be installed on a server version of the library's chosen OS, there is by most definitions no web browser available;
will the RST be made available as text (in the tarball/package) to allow copy/paste of cli lines using vi (or whatever) during the install process?
yep, thats the plan...
Hi Mason,
so these 2 wiki docs... http://wiki.koha-community.org/wiki/Debian http://wiki.koha-community.org/wiki/Koha_on_Ubuntu
convert to these 2 RST docs... http://pub.kohaaloha.com/kohadocs-sphinx/debian.html http://pub.kohaaloha.com/kohadocs-sphinx/ubuntu.html
the docs look great!
finally... I'm volunteering to be Koha's 'installation doumentation' manager a new role, similar to Nicole's 'documentation manager' role, but focusing on Koha's installation documentation only
+1 Katrin
Mason James schrieb am 10.09.2012 10:23:44
ok, so a little late... but some very successful news… :)
[…] Looks very nice, thank you for taking the time to do this evaluation!
finally... I'm volunteering to be Koha's 'installation doumentation' manager a new role, similar to Nicole's 'documentation manager' role, but focusing on Koha's installation documentation only
Nice! Why not make it official and add that position and your name to http://wiki.koha-community.org/wiki/Roles_for_3.12 ? -- Mirko
Greetings, Right now. People are probably doing “less INSTALL.blah”. Less is standard. We’ve got a perl application being installed, so perldoc isn’t a far fetched expectation. As long as we get a format where people can easily “<program> <install file>” after a “sudo apt-get install <program>”, I don’t care. Particularly if there is a README.1ST file, or just a base INSTALL file, that tells people how to read the INSTALL files. But this begs the question: are we creating a meta-problem? Additionally, the notion of converting the documents to a Wiki page makes me wonder if perhaps we have forgotten to ask the reason for having the install files. Is the INSTALL.blah file supposed to be there as an offline version of the Wiki? Perhaps, it is supposed to complement, but not replace? Right now, the current instructions that Tomas Cohen and I have worked on for Ubuntu do refer back to the Wiki page, because frankly, “just tell them to do these commands without explaining it” makes the instructions shorter. The Wiki is flushed out and explains parts a little more. I’d really like to flush it out more, but writing and testing good documentation is time consuming and I have other projects to work on. So, I’m not so keen on the convert it back to a wiki page. It also creates the problem of information overload. People skim it, think they have read and understood it, but they really have not. People want to install quickly and without hassle. Reading and following something that is a long step by step guide can be tiring, boring, and prone to error. We already have people making installation mistakes. Documentation is supposed to reduce that. So, shorter install files, and longer wikis make some sense to me. I pondered versioning the instructions for OS releases, but decided against that, since the instructions should overlap significantly between OS releases. I even started a re-attempt of Koha 3.4 on Ubuntu 8.04, but gave up as I would have to CPAN the roughly 18 modules missing. I briefly considered 3.6 and 3.8, but Perl 5.10 and Modern::Perl were a big enough stumbling block for a “new to linux” person that I figured documenting how to tweak your perl version is beyond the scope of a “normal” install. Should we split only by OS version? Well, there was a lot in there, so I better summarize/clarify (in no particular order): - Why do we include an installation instructions in the form of INSTALL.{OS} currently? - Is INSTALL.{OS} meant to be a replacement or complement to the Wiki version? - Should INSTALL.{OS} be longer, the same (identical), or shorter than the Wiki version? - Should INSTALL.{OS} be something other than plain text? How will people know how to read it? - Is INSTALL.{OS} sufficient for documentation purposes? Why not INSTALL.tarball, INSTALL.git, INSTALL.packages (which reflect the three types of install)? Why not a mix (e.g. INSTALL.tarball.{OS})? I’m just brainstorming a little. A good program needs good documentation. And I hope to help improve it. GPML, Mark Tompsett
On 2012-08-24, at 7:28 AM, Mark Tompsett wrote:
Greetings,
Right now. People are probably doing “less INSTALL.blah”. Less is standard. We’ve got a perl application being installed, so perldoc isn’t a far fetched expectation. As long as we get a format where people can easily “<program> <install file>” after a “sudo apt-get install <program>”, I don’t care. Particularly if there is a README.1ST file, or just a base INSTALL file, that tells people how to read the INSTALL files. But this begs the question: are we creating a meta-problem?
Additionally, the notion of converting the documents to a Wiki page makes me wonder if perhaps we have forgotten to ask the reason for having the install files.
Is the INSTALL.blah file supposed to be there as an offline version of the Wiki?
other way around, the wiki pages are built from the INSTALL.* files in the git repo
Should we split only by OS version?
yes, i think thats enough each INSTALL.* file contains the 2 [or 3] install methods (tarball, git, [packages]) INSTALL (a tiny file saying "please read the INSTALL file for your OS") INSTALL.Debian INSTALL.Ubuntu INSTALL.Fedora INSTALL.Centos INSTALL.Netbsd INSTALL.Openbsd INSTALL.WEB (for the web install, for all OS)
Hi, On 08/23/2012 11:14 AM, Chris Nighswonger wrote:
If we can agree to some sort of standardized formatting, I'll write a parser to generate the wiki pages from the INSTALL files.
Speaking of standardized formatting, how about AsciiDoc? [1] Some advantages: - producing HTML and other output is trivial - it wouldn't be hard to write a parser to produce MediaWiki output - based on experience from the Evergreen project, it's something that non-techie librarians can adapt to if they want to contribute changes. [1] http://www.methods.co.nz/asciidoc/ Regards, Galen -- Galen Charlton Director of Support and Implementation Equinox Software, Inc. / The Open Source Experts email: gmc@esilibrary.com direct: +1 770-709-5581 cell: +1 404-984-4366 skype: gmcharlt web: http://www.esilibrary.com/ Supporting Koha and Evergreen: http://koha-community.org & http://evergreen-ils.org
On 2012-08-23, at 4:12 PM, Mark Tompsett wrote:
Greetings,
Yes, I was hoping to getting around to cleaning up the documentation further. However until I have a 64-bit OS to attempt to install, I can't really address all the problems some people are encountering. Which bugs me, because I want good documentation for all three types of installs.
The problem is you can't write step-by-step documentation for each OS, because a tarball install under Debian, Ubuntu, CentOS are all going to encounter different problems.
nope, i disagree… its perfectly possible to write step-by-step documentation for each OS
Similarly, a git install will as well. You can only write "here's a problem you may encounter and here's an example of how to handle it". This gets compounded into a people looking for a step-by-step guide, and they'll keep hunting until they find one regardless of how dated it is.
yes, so lets remove the incorrect guides from the wiki, so people won't accidentally 'find' them.
participants (13)
-
BWS Johnson -
Chris Cormack -
Chris Nighswonger -
Fischer, Katrin -
Galen Charlton -
Mark Tompsett -
Mason James -
Mason James -
Mirko -
Paul -
Paul Poulain -
Robin Sheat -
Tomas Cohen Arazi