mirror of https://github.com/koreader/koreader
Swipe for menu and quickstart guide (#2761)
* Swipe for menu and quickstart guide Because swiping for the menu is a big change from what we're used to, this commit includes a new quickstart guide. Fixes #2608. * add some dev docs * add FileConverter spec * add QuickStart spec * add Version module * add Version specpull/2770/head
Frans de Jonge
7 years ago
committed by
GitHub
parent
6542382a0c
commit
89099e2c94
@ -0,0 +1,85 @@
|
||||
--[[--This module is responsible for generating the quickstart guide.
|
||||
]]
|
||||
local DataStorage = require("datastorage")
|
||||
local FileConverter = require("apps/filemanager/filemanagerconverter")
|
||||
local Version = require("version")
|
||||
local _ = require("gettext")
|
||||
local lfs = require("libs/libkoreader-lfs")
|
||||
local T = require("ffi/util").template
|
||||
|
||||
local QuickStart = {
|
||||
quickstart_force_show_version = 201511982,
|
||||
}
|
||||
|
||||
local quickstart_shown_version = G_reader_settings:readSetting("quickstart_shown_version") or nil
|
||||
local language = G_reader_settings:readSetting("language") or "en"
|
||||
local version = Version:getNormalizedCurrentVersion()
|
||||
local rev = Version:getCurrentRevision()
|
||||
|
||||
local quickstart_guide = T(_([[
|
||||
# KOReader Quickstart Guide
|
||||
|
||||
Welcome to KOReader. You can activate the menu by swiping down from the top of the screen. Clicking outside the menu or swiping up on the menu will discard it. Turning pages can be done either by swiping left and right or by single taps on the left or right side of the screen.
|
||||
|
||||
**Contents**
|
||||
|
||||
* [main menu](#main-menu)
|
||||
* [settings](#settings)
|
||||
* [file browser](#file-browser)
|
||||
|
||||
## Main menu <a id="main-menu"></a>
|
||||
|
||||
 You can always view this quickstart guide again through *Help* → *Quickstart guide* in the top right menu.
|
||||
|
||||
## Settings <a id="settings"></a>
|
||||
|
||||
 You can change the language and other settings through the gear icon.
|
||||
|
||||
## File browser <a id="file-browser"></a>
|
||||
|
||||
The file browser will only show document or ebook files that KOReader can read.
|
||||
|
||||
In the file browser, you can tap on any file to open it. Long press on any file to bring up a menu with more options. The location path display above the list of files and folders shows you which folder you're viewing. The `../` entry, at the top of the listed folders, lets you go *up* one level. For instance, if you are at `/mnt/onboard` now, tapping the `../` will bring you to `/mnt/`.
|
||||
|
||||
Once you have found the folder you have your books listed in, you can long press the selection that opens that folder and you should see a message box popup with the option to **Set as HOME directory**.
|
||||
|
||||
------------
|
||||
|
||||
Generated by KOReader %1.
|
||||
]]),
|
||||
rev)
|
||||
|
||||
--[[-- Returns `true` if shown, `false` if the quickstart guide hasn't been
|
||||
shown yet or if display is forced through a higher version number than when
|
||||
it was first shown.
|
||||
]]
|
||||
function QuickStart:isShown()
|
||||
if quickstart_shown_version == nil then return false end
|
||||
return (quickstart_shown_version >= self.quickstart_force_show_version)
|
||||
end
|
||||
|
||||
--[[--Generates the quickstart guide in the user's language and returns its location.
|
||||
|
||||
The fileformat is `quickstart-en-v2015.11-985-g88308992.html`, `en` being the
|
||||
language of the generated file and `v2015.11-985-g88308992` the KOReader version
|
||||
used to generate the file.
|
||||
|
||||
@treturn string path to generated HTML quickstart guide
|
||||
]]
|
||||
function QuickStart:getQuickStart()
|
||||
local quickstart_dir = ("%s/help"):format(DataStorage:getDataDir())
|
||||
local quickstart_filename = ("%s/quickstart-%s-%s.html"):format(quickstart_dir, language, rev)
|
||||
if lfs.attributes(quickstart_dir, "mode") ~= "dir" then
|
||||
lfs.mkdir(quickstart_dir)
|
||||
end
|
||||
if lfs.attributes(quickstart_filename, "mode") ~= "file" then
|
||||
local quickstart_html = FileConverter:mdToHtml(quickstart_guide, _("KOReader Quickstart Guide"))
|
||||
if quickstart_html then
|
||||
FileConverter:writeStringToFile(quickstart_html, quickstart_filename)
|
||||
end
|
||||
end
|
||||
G_reader_settings:saveSetting("quickstart_shown_version", version)
|
||||
return quickstart_filename
|
||||
end
|
||||
|
||||
return QuickStart
|
||||
@ -0,0 +1,46 @@
|
||||
--[[--
|
||||
This module helps with retrieving version information.
|
||||
]]
|
||||
|
||||
local Version = {}
|
||||
|
||||
--- Returns current KOReader git-rev.
|
||||
-- @treturn string full KOReader git-rev such `v2015.11-982-g704d4238`
|
||||
function Version:getCurrentRevision()
|
||||
if not self.rev then
|
||||
local rev_file = io.open("git-rev", "r")
|
||||
if rev_file then
|
||||
self.rev = rev_file:read()
|
||||
rev_file:close()
|
||||
end
|
||||
-- sanity check in case `git describe` failed
|
||||
if self.rev == "fatal: No names found, cannot describe anything." then
|
||||
self.rev = nil
|
||||
end
|
||||
end
|
||||
return self.rev
|
||||
end
|
||||
|
||||
--- Returns normalized version of KOReader git-rev input string.
|
||||
-- @string rev full KOReader git-rev such `v2015.11-982-g704d4238`
|
||||
-- @treturn int version in the form of a number such as `201511982`
|
||||
-- @treturn string short git commit version hash such as `704d4238`
|
||||
function Version:getNormalizedVersion(rev)
|
||||
if not rev then return end
|
||||
local year, month, revision = rev:match("v(%d%d%d%d)%.(%d%d)-?(%d*)")
|
||||
local commit = rev:match("-%d*-g(.*)")
|
||||
return ((year or 0) * 100 + (month or 0)) * 1000 + (revision or 0), commit
|
||||
end
|
||||
|
||||
--- Returns current version of KOReader.
|
||||
-- @treturn int version in the form of a number such as `201511982`
|
||||
-- @treturn string short git commit version hash such as `704d4238`
|
||||
-- @see normalized_version
|
||||
function Version:getNormalizedCurrentVersion()
|
||||
if not self.version or not self.commit then
|
||||
self.version, self.commit = self:getNormalizedVersion(self:getCurrentRevision())
|
||||
end
|
||||
return self.version, self.commit
|
||||
end
|
||||
|
||||
return Version
|
||||
@ -0,0 +1,50 @@
|
||||
describe("FileConverter module", function()
|
||||
local FileConverter
|
||||
setup(function()
|
||||
require("commonrequire")
|
||||
FileConverter = require("apps/filemanager/filemanagerconverter")
|
||||
end)
|
||||
it("should show conversion support for Markdown", function()
|
||||
assert.is_true(FileConverter:isSupported("/markdown_file.md"))
|
||||
end)
|
||||
it("should not show conversion support for PDF", function()
|
||||
assert.is_false(FileConverter:isSupported("/pdf_file.pdf"))
|
||||
end)
|
||||
it("should convert Markdown to HTML", function()
|
||||
local markdown = [[
|
||||
# KOReader Quickstart Guide
|
||||
|
||||
Welcome to KOreader. You can activate the menu by swiping down from the top of the screen. Clicking outside the menu or swiping up on the menu will discard it. Turning pages can be done either by swiping left and right or by single taps on the left or right side of the screen.
|
||||
|
||||
**Main menu**
|
||||
|
||||
 You can always view this quickstart guide again through *Help* → *Quickstart guide* in the top right menu.
|
||||
|
||||
**Settings**
|
||||
|
||||
 You can change the language and other settings through the gear icon.
|
||||
|
||||
------------
|
||||
|
||||
Generated by KOReader v2015.11-982-g704d4238.
|
||||
]]
|
||||
local title = "KOReader Quickstart Guide"
|
||||
local html_expected = [[<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>KOReader Quickstart Guide</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>KOReader Quickstart Guide</h1>
|
||||
<p>Welcome to KOreader. You can activate the menu by swiping down from the top of the screen. Clicking outside the menu or swiping up on the menu will discard it. Turning pages can be done either by swiping left and right or by single taps on the left or right side of the screen.</p>
|
||||
<p><strong>Main menu</strong></p>
|
||||
<p><img alt="Menu" src="../resources/icons/menu-icon.png"> You can always view this quickstart guide again through <em>Help</em> → <em>Quickstart guide</em> in the top right menu.</p>
|
||||
<p><strong>Settings</strong></p>
|
||||
<p><img alt="Settings" src="../resources/icons/appbar.settings.png"> You can change the language and other settings through the gear icon.</p>
|
||||
<hr>
|
||||
<p>Generated by KOReader v2015.11-982-g704d4238.</p>
|
||||
</body>
|
||||
</html>]]
|
||||
assert.are.same(html_expected, FileConverter:mdToHtml(markdown, title))
|
||||
end)
|
||||
end)
|
||||
@ -0,0 +1,36 @@
|
||||
describe("QuickStart module", function()
|
||||
setup(function()
|
||||
require("commonrequire")
|
||||
end)
|
||||
it("should return false shown_version lower than force_show_version", function()
|
||||
G_reader_settings:saveSetting("quickstart_shown_version", 1)
|
||||
G_reader_settings:flush()
|
||||
local QuickStart = require("ui/quickstart")
|
||||
QuickStart.quickstart_force_show_version = 2
|
||||
assert.is_false(QuickStart:isShown())
|
||||
end)
|
||||
it("should return true when shown_version equal to force_show_version", function()
|
||||
G_reader_settings:saveSetting("quickstart_shown_version", 1)
|
||||
G_reader_settings:flush()
|
||||
local QuickStart = require("ui/quickstart")
|
||||
QuickStart.quickstart_force_show_version = 1
|
||||
assert.is_true(QuickStart:isShown())
|
||||
end)
|
||||
it("should return true when shown_version higher than force_show_version", function()
|
||||
G_reader_settings:saveSetting("quickstart_shown_version", 2)
|
||||
G_reader_settings:flush()
|
||||
local QuickStart = require("ui/quickstart")
|
||||
QuickStart.quickstart_force_show_version = 1
|
||||
assert.is_true(QuickStart:isShown())
|
||||
end)
|
||||
it("should return a proper quickstart filename", function()
|
||||
local DataStorage = require("datastorage")
|
||||
local QuickStart = require("ui/quickstart")
|
||||
local Version = require("version")
|
||||
local language = "en"
|
||||
local rev = Version:getCurrentRevision()
|
||||
local quickstart_dir = string.format("%s%s", DataStorage:getDataDir(), "/help")
|
||||
local expected_quickstart_filename = ("%s/quickstart-%s-%s.html"):format(quickstart_dir, language, rev)
|
||||
assert.is.same(expected_quickstart_filename, QuickStart:getQuickStart())
|
||||
end)
|
||||
end)
|
||||
@ -0,0 +1,28 @@
|
||||
describe("Version module", function()
|
||||
local Version
|
||||
setup(function()
|
||||
require("commonrequire")
|
||||
Version = require("version")
|
||||
end)
|
||||
it("should get current revision", function()
|
||||
assert.is_true(22 >= (Version:getCurrentRevision()):len())
|
||||
end)
|
||||
it("should get normalized current version", function()
|
||||
assert.is_true(9 >= tostring(Version:getNormalizedCurrentVersion()):len())
|
||||
end)
|
||||
it("should get normalized version", function()
|
||||
local rev = "v2015.11-982-g704d4238"
|
||||
local version, commit = Version:getNormalizedVersion(rev)
|
||||
local expected_version = 201511982
|
||||
local expected_commit = "704d4238"
|
||||
assert.are.same(expected_version, version)
|
||||
assert.are.same(expected_commit, commit)
|
||||
end)
|
||||
it("should fail gracefully", function()
|
||||
local version, commit = Version:getNormalizedVersion()
|
||||
local expected_version = nil
|
||||
local expected_commit = nil
|
||||
assert.are.same(expected_version, version)
|
||||
assert.are.same(expected_commit, commit)
|
||||
end)
|
||||
end)
|
||||
Loading…
Reference in New Issue