docs: structuring and overhaul

Signed-off-by: Paul Donald <newtwen@gmail.com>

docs/ModulesHowTo.md

@@ -1,4 +1,4 @@
-# HowTo: Write Modules
+# HowTo: Write Lua based Modules (deprecated for client side modules)
 
 See [online wiki](https://github.com/openwrt/luci/wiki/ModulesHowTo) for latest version.
 
@@ -7,34 +7,34 @@ See [online wiki](https://github.com/openwrt/luci/wiki/ModulesHowTo) for latest
 This tutorial describes how to write your own modules for the LuCI WebUI.
 For this tutorial we refer to your LuCI installation directory as `lucidir` (`/usr/lib/lua/luci` on your OpenWRT device) and assume your LuCI installation is reachable through your webserver via `http://192.168.1.1/cgi-bin/luci`.
 
-The recommended way to set up development environment:
+The recommended way to set up a development environment:
 
-Install OpenWRT on your router/device (You could use a QEMU or VirtualBox image instead)
+- Install OpenWRT on your router/device (You could use a QEMU or VirtualBox image instead)
 
-Install SSHFS on your host
+- Install SSHFS on your host
 
-Mount your routers' root (/) someplace on your development host (eg. /mnt/router)
+- Mount your routers' root (`/`) someplace on your development host (eg. `/mnt/router`)
 
-Then open /mnt/router/(lucidir) in your favorite development studio
+- Then open `/mnt/router/(lucidir)` in your favorite development studio
 
-Extra: Add configurations to your dev studio which will delete the luci cache (detailed below) and then open a browser window to your routers' configuration page in order to see your module/application.
+Extra:
+- Add configurations to your dev studio which will delete the luci cache (detailed below) and then open a browser window to your routers' configuration page in order to see your module/application.
 
 
 When testing, if you have edited index files, be sure to remove the folder `/tmp/luci-modulecache/*` and the file(s) `/tmp/luci-indexcache*`, then refresh the LUCI page to see your edits.
 
-## Show me the way (The dispatching process)
-To write a module you need to understand the basics of the dispatching process in LuCI.
-LuCI uses a dispatching tree that will be built by executing the index-Function of every available controller.
+## The dispatching process
+LuCI uses a dispatching tree that is built by executing the index-Function of every available controller.
 The CGI-environment variable `PATH_INFO` will be used as the path in this dispatching tree, e.g.: `/cgi-bin/luci/foo/bar/baz`
-will be resolved to `foo.bar.baz`
+resolves to `foo.bar.baz`.
 
-To register a function in the dispatching tree, you can use the `entry`-function of `luci.dispatcher`. It takes 4 arguments (2 are optional):
+To register a function in the dispatching tree, use the `entry`-function of `luci.dispatcher`. It takes 4 arguments (2 are optional):
 ```lua
 entry(path, target, title=nil, order=nil)
 ```
 
 * `path` is a table that describes the position in the dispatching tree: For example a path of `{"foo", "bar", "baz"}` would insert your node in `foo.bar.baz`.
-* `target` describes the action that will be taken when a user requests the node. There are several predefined ones of which the 3 most important (call, template, cbi) are described later on this page
+* `target` describes the action that will be taken when a user requests the node. There are several predefined actions, of which the 3 most important (call, template, cbi) are described later on this page
 * `title` defines the title that will be visible to the user in the menu (optional)
 * `order` is a number with which nodes on the same level will be sorted in the menu (optional)
 
@@ -46,8 +46,8 @@ You can assign more attributes by manipulating the node table returned by the en
 * `sysauth` requires the user to authenticate with a given system user account
 
 
-# It's all about names (Naming and the module file)
-Now that you know the basics about dispatching, we can start writing modules. Now, choose the category and name of your new digital child.
+# Naming and the module file
+Now we can start writing modules. Choose the category and name of your new digital child.
 
 Let's assume you want to create a new application `myapp` with a module `mymodule`.
 

docs/README.md

@@ -4,5 +4,21 @@ See Wiki [LuCI Technical Reference](https://openwrt.org/docs/techref/luci)
 
 ## API Reference
 
- - [Client side JavaScript APIs](jsapi/)
- - [Server side Lua APIs](api/index.html)
+- [Client side JavaScript APIs](jsapi/)
+- [How to i18n your module](i18n): internationalization via \*.po and \*.pot files
+- [How to make LuCI JS Modules](https://github.com/openwrt/luci/tree/master/applications/luci-app-example): see the luci-app-example in the repo
+- [How to use the JSON-RPC](JsonRpcHowTo)
+- [How to make themes](ThemesHowTo)
+- [LuCI Modules Reference](Modules): can be JS based or Lua (deprecated)
+
+## Deprecated API Reference (older Lua based APIs)
+
+- [CBI models reference](CBI):CBI models are Lua files describing the structure of an UCI config file and the resulting HTML form to be evaluated by the CBI parser
+- [How to make LuCI Lua Modules](ModulesHowTo): No new Lua modules for client side display are accepted, but some server side things are still done in Lua
+- [LMO - Lua Machine Objects](LMO): to pack language strings into a more efficient form for Lua
+- [Server side Lua APIs](api/index.html)
+- [Templates](Templates): template processor which parses HTML-files to Lua functions and allows to store precompiled template files
+
+## Archived
+
+- [LuCI-0.10](LuCI-0.10): No longer used, but useful reference if you encounter older LuCI versions.

docs/i18n.md

@@ -6,7 +6,7 @@ See [online wiki](https://github.com/openwrt/luci/wiki/i18n) for latest version.
 
 ### Translations in JavaScript
 
-Wrap translatable strings with `_()` e.g.  `_('string to translate')` and the `i18n-scan.pl` and friends will correctly identify these strings as they do with all the existing translations.
+Wrap translatable strings with `_()` e.g.  `_('string to translate')` and the `i18n-scan.pl` and friends will correctly identify these strings for translation.
 
 If you have multi line strings you can split them with concatenation:
 ```js
@@ -23,25 +23,19 @@ var mystr = _('this string will translate \
 	a multi line string');
 ```
 
-Usually if you have multiple sentences you may need to use a line break then use the `<br />` HTML tag:
-```js
-var mystr = _('Port number.<br />' +
-	'E.g. 80 for HTTP');
-```
-
-To simplify a job for translators it may be better to split into separate keys without the `<br />`:
+Usually if you have multiple sentences you may need to use a line break. Use the `<br />` HTML tag like so:
 ```js
 var mystr = _('Port number.') + '<br />' +
 	_('E.g. 80 for HTTP');
 ```
-Please use `<br />` and **not** `<br>` or `<br/>`.
+Use `<br />` and **not** `<br>` or `<br/>`.
 
-If you have a link inside a translation then try to move its attributes out of a translation key like:
+If you have a link inside a translation, move its attributes out of a translation key:
 ```js
 var mystr = _('For further information <a %s>check the wiki</a>')
 	.format('href="https://openwrt.org/docs/" target="_blank" rel="noreferrer"')
 ```
-This will generate a full link with HTML `For further information <a href="https://openwrt.org/docs/" target="_blank" rel="noreferrer">check the wiki</a>`. The `noreferrer` is important when making a link that is opened in a new tab (`target="_blank"`).
+This will generate a full link with HTML `For further information <a href="https://openwrt.org/docs/" target="_blank" rel="noreferrer">check the wiki</a>`. The `noreferrer` is important so that it is opened in a new tab (`target="_blank"`).
 
 ### Translations in LuCI lua+html templates
 Use the `<%: text to translate %>` as documented on [Templates](./Templates.md)
@@ -54,7 +48,7 @@ In most controller contexts, this is already available for you, but if necessary
 ## Translation files
 Translations are saved in the folder `po/` within each individual LuCI component directory, e.g. `applications/luci-app-acl/po/`.
 The template is in `po/templates/<package>.pot`.
-The actual translation files can be found at `po/[lang]/[package].po`.
+The individual language translation files can be found at `po/[lang]/[package].po`.
 
 In order to use the commands below you need to have the `gettext` utilities (`msgcat`, `msgfmt`, `msgmerge`) installed on your system.
 On Debian/Ubuntu, install them with `sudo apt install gettext`.