Help message: Offline Wiki bundled with koreader-updates #1371
Comments
|
Okay, I just did a quick test: git clone git@github.com:koreader/koreader.wiki.git
cd koreader.wiki
pandoc *.md --toc --from markdown_github -o help.epubThe resulting TOC looks slightly confusing, but overall it's not bad at all. |
|
Got it, thanks! I think that the I would suggest more than one epub. Separating the Chinese from the English might be a good start. Separating user from developer seems sensible. Separating all install instructions from the usage instructions seems wise as most will already be reading on their device. |
|
Unfortunately |
|
I don't know if Pandoc is the best tool for this particular job, although I do consider it the best for actually writing stuff in general. (In the rare case that it falls short you can just include straight LaTeX, while maintaining Pandoc Markdown's legibility for all your other stuff.) Something involving Gollum might make more sense in this particular case. |
|
Feature wise, pandoc will no doubt be the best tooling out there. It might take awhile to configure pandoc to do what we want though. Someone is already trying to do similar stuff: jgm/pandoc#1857. Another alternative is to write a tiny script in lua, leveraging the markdown parser used by ldoc. Either way, I think this automated wiki to book tooling can be turned into a decent open-source project that we can share with the community. Given the fact that a lot of projects out there are using github wiki as documentation, it will help many people ;) |
|
BTW, If anyone volunteers to do this, we can add this ticket to the next stable release milestone too. |
Haha, this is getting fancy ;) What concern do you have with this workflow? |
|
Too many intermediaries: Seems like begging for high maintenance. |
|
It will be simpler if you think of it as two parallel workflows:
And we bridge them with git commits. Then again, this is a nice to have feature that I don't expect it to happen in the near future ;) |
|
I noticed an interesting blog post: http://blog.terryburton.co.uk/2015/02/20/Creating-PDF-Documentation-From-a-GitHub-Wiki-Using-Pandoc.html (see https://gist.github.com/rogersachan/40e4f69439b26e1f096f8c91e98b1dee for a potentially updated version) Filter: rewritewikilinks.hs#!/usr/bin/env runhaskell
import Text.Pandoc.JSON
import Data.Char
main = toJSONFilter rewritewikilinks
rewritewikilinks :: Inline -> [Inline]
rewritewikilinks ( Link txt ('#':url,title) ) = [ ( Link txt ("#"++url,title) ) ]
rewritewikilinks ( Link txt ('h':'t':'t':'p':':':url,title) ) = [ ( Link txt ("http:"++url,title) ) ]
rewritewikilinks ( Link txt ('h':'t':'t':'p':'s':':':url,title) ) = [ ( Link txt ("https:"++url,title) ) ]
rewritewikilinks ( Link txt (url,title) ) = [ ( Link txt ("#" ++ map toLower url,title) ) ]
rewritewikilinks x = [x]Adding the whole haskell-platform stuff would be pretty heavy and when I just tried it I got an error I don't quite understand: Still, it's the main missing link. Edit: I'm not entirely sure what the problem is, but the quite elaborate GitHub wiki to PDF system can be admired by checking out the postscriptbarcode wiki: |
|
@Frenzie I've tried Why not gitbook? |
|
@pazos That was just a quick proof of concept illustration of the principle that probably took me about half a minute to come up with back when I wrote it. Obviously it would need the kind of work that can be seen in the __pandoc directory of the postscriptbarcode.wiki repository to be usable. There are two points I'd like to keep in mind:
A quick look at Gitbook suggests it's harder to use than the GitHub wiki. Documentation is the perfect area to contribute without needing to be able to read code or work with git. On GitHub, all you need is a GitHub account. |
true Also, not all the pages of the wiki are relevant for an "getting started" epub. Just something like:
|
|
I feel like we might need to maintain two separate documentations, one for developers and one for users. The current wiki is a mix of both :( |
|
I think dev docs are also much more automatable as has already been done.
…On Feb 24, 2017 10:21, "Qingping Hou" ***@***.***> wrote:
I feel like we might need to maintain two separate documentations, one for
developers and one for users.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1371 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAMYBcitLkSbj3M1BKRCBSIpsx-Cp_MZks5rfqESgaJpZM4DLACE>
.
|
This commit seeks to improve the paltry help menu item. It breaks the "try to have at least three items in a submenu" rule in anticipation of an upcoming quickstart guide and show quickstart guide setting. This guide will explain that (soon) you will have to swipe south at the top of the screen to activate the menu. Also see the somewhat related koreader#1371, which would also go in the submenu.
This commit seeks to improve the paltry help menu item. It breaks the "try to have at least three items in a submenu" rule in anticipation of an upcoming quickstart guide and show quickstart guide setting. This guide will explain that (soon) you will have to swipe south at the top of the screen to activate the menu. Also see the somewhat related #1371, which would also go in the submenu.
|
To make life easier I'm cleaning up the wiki a little. Here's a list of dev pages. Checkmarks indicate they should be safe to be deleted (soon).
The base wiki should also be migrated but that's of less immediate concern. |
|
Hm, working with the wiki I'm inclined to agree with @pazos that the GitHub wiki is kind of terrible. The main problem is no folder structure in the online interface, although you can do it offline. I brought some order into the whole shebang offline but if you use folders with individual _Sidebar.md documents you can't edit those in the web GUI, for example. As I pointed out before, the main problem with many alternatives is that they're too developer-oriented. That's fine for the developer docs, but the user docs should be easier to edit than that. Other than a GitHub account (preferably not a separate account) the entry barrier should be as low as possible. It occurred to me that the likes of http://daux.io (and maybe https://www.gitbook.com/ too?) are potentially significantly less bad than I alluded above because GitHub includes an online editor interface. It's potentially a little less obvious than the wiki, but you shouldn't actually have to figure out Git. Some more possible inspiration here: https://github.com/PharkMillups/beautiful-docs
Actually I'm not sure why that links to https://github.com/justinwalsh/daux.io/blob/master/docs/00_Getting_Started.md and not directly to https://github.com/justinwalsh/daux.io/edit/master/docs/00_Getting_Started.md The probably more ubiquitous RTD has the same feature combined with what I consider the same oddity: http://docs.sylius.org/en/latest/ RTD looks very promising because it comes with automated EPUBs and localization. The less work for me/us the better. ;-) NB They advise reStructuredText (Sphinx) although they also support Markdown. Anyway, Markdown to rST is a piece of cake with Pandoc, so that's certainly no problem. What are your thoughts on or experiences with these systems? |
|
http://www.mkdocs.org/ also looks interesting, demo at http://doc.freshrss.org/en/ (which I mistakenly thought was RTD because it uses the same theme) It would require more effort: |
|
mkdocs and daux.io seem to be focused more on developers. gitbook looks promising although I am not sure how the collaborator restriction is going to affect us. I would be looking for the following features for the solution:
|
|
5 collaborators (Gitbook) is pretty minuscule. So far I think RTD is the closest that I've come across, although it's not quite ideal. |
|
RTD requires the doc to be written in python tooling and managed by git. In that case, it would be more flexible for us to just setup the automated doc build in gitlab CI. RTD is really just a doc CI ;P |
|
awesome work on dev documentation @Frenzie !!! Any update on user documentation? Can we setup a separate repo for a quickstart guide, keep the documentation on markdown and convert it to html or latex using pandoc/scidown? |
|
@pazos Could you please clarify what you mean precisely in contrast to the present situation? |
|
@Frenzie: I'm not sure if we can handle the github wiki as a normal repo (I mean being able to review PRs, submit issues, have visible discussion, etc) or even submit new code outside the markdown articles. I mean a full repo with contributing guides, a bit of discussion about guide/book toc, and a Makefile to automate the process of building the output formats (at least html and epub). I find github's wiki pretty decent as a hub that redirect users to proper documentation. Required wiki contents are installation for different devices, and building koreader from source, the user guide can be stored elsewhere an linked to koreader.rocks and to the wiki, as dev docs are. |
You can pretty much put whatever you want in there, but indeed it's a pain. It's true that converting the wiki to a regular GH repo shouldn't really be much worse in any case. You'd lose the sidebar, but you'd gain visible folder structure. (I already put the wiki into a folder structure, but you can only see if if you clone the repo.) We could consider tapping into Jekyll (GitHub Pages)? |
Sure. I cloned the wiki and I'm going to spend some time testing outputs with pandoc. For future sake I would use pandoc's --table-of-contents switch and let it generate the toc from #h1-h3 headers. |
|
As an aside, the |
|
Also of potential interest, Prose.io. See https://bugherd.com/blog/building-a-better-github-wiki/ Gitbook has added something about contacting them for FOSS. |
|
This might be of use, but it seems to be slightly inactive recently. Also of interest, though I'm not sure I want to pollute the main repo with that: |
|
Cf. #7757 (comment) and following for some related discussion.
So change the content. ;-)
You have a unique talent for writing things that don't land well with me, lol. ;-D I think the vast majority of my discussion was focused on contributing. The discussion is four years old. Four years ago I put in a fair bit of cleaning effort, albeit not with regard to screenshots (incidentally the icon change was a few months back; other visual changes have been significantly more minor): #1371 (comment). I've half-heartedly attempted to keep the sidebar vaguely organized but I don't have the time to keep a close eye on the code and the (user) documentation. Especially since I do directly manage the localization effort. I depend on @AlanSP1 for example to convert information from the release notes I write into wiki content/updates, and I very much appreciate that.
No one's happy with GitHub wiki. [Edit: cf. #7742] NB Ideally an alternative would also integrate with Weblate.
Me too! ;-) I've worked as an editor. While I haven't used Scribus professionally, I've done so with InDesign and Acrobat.
Could you please expand on some of the advantages and disadvantages compared to GH wiki? (Pay no mind to the fact that you'll mostly be saying stuff I already know. Others may not have worked much with comments and track changes and whatnot. And even so, I'm still curious about your knowledge of the commit log equivalent since I've only worked with Word/Google Docs in relatively formal step by step or small <5 contributor informal workflows, how to export/integrate these things with other platforms, what kind of automation may be available as an option, etc.) |
My writing style is short and effective so it might come as offending to some people. I got this reaction before. Please don't take it personally. I am not attacking anyone. Writing and maintaining code leaves little time for documentation. I am not criticizing developers for not updating wiki. I am pointing out to the lack of contribution by other users/members.
After pazos and NiLuJe's encouragement in the referenced thread I started building a document. After going around wiki I can say this job doesn't need github wiki or any other kind of collaborative tool. I have the impression that KOReader nearly reached maturity (correct me if I am wrong). Maybe some new device support or color e-ink addition in the future. Maybe a few plugins for extra services. But majority of changes will be fixes for issues and bugs and maybe some optimisations. I can't think of anything that will require heavy contributions of many people. And KOReader is not (and will not be) at the size of DARKTABLE or GIMP or BLENDER. So this is more like a one-man job, not community effort. My plan:
So to answer your question:
Disadvantages:
|
Feature wise yes, UI wise less so. Or at least that's my opinion, ymmv.
New wiki page from yesterday, btw. :p https://github.com/koreader/koreader/wiki/Clipboard
I didn't realize you meant it so traditionally. I figured you meant Google Docs or equivalent, with an editorial team. You're welcome to do it that way of course, but you might run into a lot of merge conflicts. That is, I suspect at the very least @NiLuJe and I will make copious use of track changes and comments. The nature of online editing streamlines that slightly better. |
There are much better options for extracting text from documents. Evernote export, KOHighlights and Calibre plugin (4 if we count manual extraction from metadata.lua). I would say any user that bypasses these 4 easier options to manually copy paste text into a file on a slow e-reader should be pretty advanced and should not need any instructions for copy/paste. Also if I would add this to the guide I am preparing, title would be "How can I save parts of my book into a text file on my device ?" which denotes a process, a problem that user needs to solve. How discoverable is the title "CLIPBOARD" for a user with a question like this ? By the way here is a rough draft of document to show you what I have in my mind.
And regarding this: You can edit the file directly. I don't have to be the gatekeeper. I am sure you both have office installed on your computers. If you can write in wiki you can surely write it into an office document. |
|
Just, you can't say people don't care. ;-)
Great! 👍
But you have to take up the coordinator role ("gatekeeper") for a more traditional workflow. At a publisher's you (or at least we) use something like shared Excel sheets or Jira to track who's working on what. A bit primitive perhaps but it works. That's overkill, but the basic issue it solves still exists. The problem is it's actually worse, because the nature of our community is more half a page here and half a page there because, well… it's not work. ^_^ |
|
After some thinking I decided to clarify my position regarding documentation. I suspect I might be misunderstood: This guide just aims to help new users to get introduced to KOReader basics.
These are pretty basic things that users need just after installing. For example "long press to set as default" should be one of the first things a user needs to learn because someone transferring from stock reader apps would like to set the fonts and styling according to their habits so new books will be opened with these defaults. My guide will be helpful conveying this kind of basic information. For advanced usage cases, guide will direct users to wiki where deeper and fresher information can be found. For example this info I found in wiki is pretty critical so it should be included in my guide:
But ssh access is pretty advanced so I can just say: |
As not quite an aside, both long-press for more information and long-press to set default are mentioned in the quickstart guide.
Perhaps that's more true for Chinese? I don't feel that the results differ that much between auto and large (as they do with small). In fact at a quick glance I only see a worse result with a quick random test.
And small for good measure: |
I wonder who wrote this ? Maybe we should contact the author so he can fix his entry :)
|
|
Sorry, I think I shouldn't be here but months ago I asked exactly for this (user guide) file. #7082 (comment) |
|
@Zeyadas: Most, if not all, of the stuff that is in there should never ever be touched by a human being anymore. We took pain over the years to make most of the relevant ones exposed somewhere in the UI. The glaring exception would be the tap zones (I keep intending to write a real wiki page about it), and what's left in https://github.com/koreader/koreader/wiki/Change-defaults (which I did a pass on a while back, but may still not be entirely up to date). |
NB That's a GH wiki issue. I merely organized it into a folder in 2017. It was written by chrox in 2014. ;-) With regard to the content, presumably I reasoned the same way as above. If I felt large were better I'd push to make it the default instead of babbling about it somewhere hidden in the wiki. |
After reading @chrox last wiki updates --much needed because I had forgotten what Zsync was about-- I realize that the help function still point to the website for bug reports.
I would love it if it also referred to the to-be-constructed offline wiki of koreader. Every time a new update for koreader is created, the current wiki is again bundled. It could be read in crengine without the need to wait for Wifi.
Thus the work in the wiki becomes more available and an integral part of koreader.
Of course other ways of opening up the wiki content inside koreader could be nice, too: a menu item for help with a topic list and a scrollable popup much like the dictionary windows.
The text was updated successfully, but these errors were encountered: