markdown doc: more work; added support for other doc pages and TOC

.gitignore

@@ -3,6 +3,7 @@ build.*
 
 src/version.c
 src/tvh_locale_inc.c
+src/docs_inc.[ch]
 src/webui/extjs-std.c
 src/webui/extjs-debug.c
 src/webui/extjs-tv-std.c

Makefile

@@ -541,9 +541,11 @@ ALL-$(CONFIG_DVBSCAN)     += check_dvb_scan
 # Documentation
 #
 
-MD-CLASS = $(patsubst docs/class/%.md,%,$(wildcard docs/class/*.md))
 SRCS-yes += src/docs.c
 I18N-C   += src/docs_inc.c
+I18N-DOCS = $(wildcard docs/markdown/*.md) $(wildcard docs/class/*.md)
+MD-ROOT   = $(patsubst docs/markdown/%.md,%,$(wildcard docs/markdown/*.md))
+MD-CLASS  = $(patsubst docs/class/%.md,%,$(wildcard docs/class/*.md))
 
 #
 # Internationalization
@@ -662,18 +664,30 @@ $(BUILDDIR)/build.o: $(BUILDDIR)/build.c
 	$(pCC) -c -o $@ $<
 
 # Documentation
-$(BUILDDIR)/docs-timestamp: $(MD-FILES) support/doc/md_to_c.py
+$(BUILDDIR)/docs-timestamp: $(I18N-DOCS) support/doc/md_to_c.py
 	@-rm -f src/docs_inc.c
+	@for i in $(MD-ROOT); do \
+	   echo "Markdown: docs/markdown/$${i}.md"; \
+	   support/doc/md_to_c.py --in="docs/markdown/$${i}.md" \
+	                          --name="tvh_doc_root_$${i}" >> src/docs_inc.c || exit 1; \
+	 done
 	@for i in $(MD-CLASS); do \
-	   echo "Markdown class: $${i}"; \
+	   echo "Markdown: docs/class/$${i}.md"; \
 	   support/doc/md_to_c.py --in="docs/class/$${i}.md" \
-	                          --name="tvh_doc_$${i}_class" >> src/docs_inc.c; \
+	                          --name="tvh_doc_$${i}_class" >> src/docs_inc.c || exit 1; \
+	 done
+	@printf "\n\nconst struct tvh_doc_page tvh_doc_markdown_pages[] = {\n" >> src/docs_inc.c
+	@for i in $(MD-ROOT); do \
+	   echo "  { \"$${i}\", tvh_doc_root_$${i} }," >> src/docs_inc.c || exit 1; \
 	 done
+	@echo "  { NULL, NULL }," >> src/docs_inc.c || exit 1
+	@echo "};" >> src/docs_inc.c
 	@touch $@
 
 src/docs_inc.c: $(BUILDDIR)/docs-timestamp
+src/docs_inc.h: $(BUILDDIR)/docs-timestamp
 
-$(BUILDDIR)/src/docs.o: src/docs_inc.c
+$(BUILDDIR)/src/docs.o: src/docs_inc.c $(I18N-DOCS) support/doc/md_to_c.py
 
 # Internationalization
 .PHONY: intl

docs/markdown/configure_tvheadend.md

@@ -0,0 +1,150 @@
+##Configure Tvheadend
+
+This section gives a high-level overview of the steps needed to get Tvheadend
+up and running. For more detailed information, please consult the rest of
+this guide - much of it is arranged in the same order as the tabs on the
+Tvheadend interface so you know where to look.
+
+You can also consult the in-application help text, which mirrors this guide
+to a very great extent.
+
+###1. Ensure Tuners are Available for Use
+
+**Tvheadend web interface: _Configuration -> DVB Inputs -> TV Adapters_**
+
+On this tab, you'll see a tree structure, with the Linux device list at the
+top level (e.g. `/dev/dvb/adapter0`)
+
+Individual tuners are then the next level down (e.g. `DiBcom 7000PC : DVB-T #0`)
+
+Click on each tuner that you want Tvheadend to use, and ensure "Enabled"
+is checked in the 'Parameters' list
+
+If anything is obviously wrong at this point, you probably have a
+driver/firmware error which you'll need to resolve before going any further.
+
+###2. Set up Relevant Network(s)
+
+**Tvheadend web interface: _Configuration -> DVB Inputs -> Networks_**
+
+Create a network of the appropriate type here. You can have multiple networks
+of the same type as necessary, e.g. to have two DVB-T networks defined,
+one with HD muxes, one without.
+
+The creation process allows you to select from a series of pre-defined mux
+lists for common DVB sources. These are maintained outside of Tvheadend, and
+are downloaded from [linuxtv](http://git.linuxtv.org/cgit.cgi/dtv-scan-tables.git/) -
+but they do go out of date as broadcasters move services around and national
+authorities change entire pieces of spectrum. As such, you should try the
+pre-defined values, but you may need to add muxes manually.
+
+**TODO: Critical configuration items at this stage: ........**
+
+###3. Associate the Network with the Respective Tuner(s)
+
+**Tvheadend web interface: _Configuration -> DVB Inputs -> TV Adapters_**
+
+Associate each of your tuners with the correct network through _Parameters -> Basic Settings_. 
+
+This can be as simple or as complex as necessary. You may simply have, for
+example, a single DVB-S2 network defined and then associate this with all
+DVB-S2 tuners. Or, you might have multiple networks defined - different
+satellites, different encoding. So, as further examples, you might define
+and then associate an HD DVB-T2 (e.g. H.264) network with HD tuners, while
+having a separate SD network associated with an independent SD (e.g. MPEG-2)
+tuner. 
+
+**TODO: Critical configuration items at this stage: ........**
+
+At this point, your tuners now know what networks to use: one network can
+appear on multiple tuners (many-to-one), and one tuner can have multiple
+networks.
+
+### 4. If Necessary, Manually Add Muxes
+
+**Tvheadend web interface: _Configuration -> DVB Inputs -> Muxes_**
+
+Ideally, this is where you'll see a list of the pre-populated muxes as created
+when you set up your initial network. However, should there be any issues,
+this is where you can manually add missing muxes. You only really need to
+worry about this if the pre-defined list didn't work (e.g. because of
+out-of-date data as broadcasters re-arrange their services or because automatic
+detection hasn't successfully found all the muxes over time. 
+
+If you do need to add something manually, you'll need to search the Internet
+for details of the appropriate transmitter and settings: satellites tend not
+to change much and are universal over a large area, but terrestrial muxes
+are typically very localised and you'll need to know which specific transmitter
+you're listening to. 
+
+Good sources of transmitter/mux information include:
+
+* [KingofSat](http://en.kingofsat.net) for all European satellite information
+
+* [ukfree.tv](http://www.ukfree.tv/maps/freeview) for UK DVB-T transmitters
+
+* [Interactive EU DVB-T map](http://www.dvbtmap.eu/mapmux.html) for primarily
+central and northern Europe
+
+> other major sources....?
+##NOTE: TODO: TEXT REQUIRED
+
+You can also use [dvbscan](http://www.linuxtv.org/wiki/index.php/Dvbscan) to
+force a scan and effectively ask your tuner what it can see.
+
+**TODO: Critical configuration items at this stage: ........**
+
+### 5. Scan for Services
+
+**Tvheadend web interface: _Configuration -> DVB Inputs -> Services_**
+
+This is where the services will appear as your tuners tune to the muxes based
+on the network you told them to look on. Again, remember what's happening: 
+Tvheadend is telling your tuner hardware (via the drivers) to sequentially
+tune to each mux it knows about, and then see what 'programmes' it can see
+on that mux, each of which is identified by a series of unique identifiers
+that describe the audio stream(s), the video stream(s), the subtitle stream(s)
+and language(s), and so on.
+
+(For the technically-minded, these unique identifiers - the elementary streams
+- are referred to as 'packet identifiers' or 'PIDs').
+
+> To force a scan ...
+##NOTE: TODO: TEXT REQUIRED
+
+### 6. Map Services to Channels
+
+Once scanning for services is complete, you need to map the services to 
+channels so your client can actually request them (i.e. so you can watch
+or record). You can do this in two places:
+
+**Tvheadend web interface: _Configuration -> DVB Inputs -> Services_**
+
+Press the "Map All" button. Note the resultant dialog box that allows you
+to exclude some services from the mapping: this is covered in more detail
+later in this guide. 
+
+**Tvheadend web interface: _Configuration -> Channel/EPG -> Channels_**
+
+Press the "Map Services" button. Again, you can exclude services as you
+can for 'Map All', above.
+
+> Any explanation on how a channel can map to multiple services <......>
+
+> Anything about using bouquets
+##NOTE: TODO: TEXT REQUIRED
+
+### 7. Watch TV
+
+That's it - you're done. You should now have a working basic Tvheadend
+installation with channels mapped and ready for use!
+
+As required, you may now wish to look into:
+
+* Setting up different EPGs (inc. localised character sets and timing offsets)
+* Setting up channel icons
+* Setting up recording profiles
+* Setting up streaming profiles (including transcoding)
+* Arranging your channels into groups (channel tags)
+* Setting up softcams for descrambling
+* Setting up access control rules for different client types/permission levels

docs/markdown/index.md

@@ -0,0 +1,19 @@
+#Tvheadend 4.2 User Guide
+
+![Tvheadend Logo](images/logobig.png)
+
+#Purpose
+
+This document is intended to give you a high-level overview of how to set 
+up Tvheadend for the first time. It does not aim to provide a complete description
+of every step or answer every question: more details are available on the
+tvheadend [wiki](https://tvheadend.org/projects/tvheadend/wiki).
+
+As you set things up, consult the on-line (web interface) help as well.
+Tvheadend includes copies of many of these pages in the application, which
+is easier to find when you're wondering what to do next.
+
+If you get really stuck, there's the [forum](https://tvheadend.org/projects/tvheadend/boards)
+and IRC (*#hts* on *freenode*) - [Kiwi IRC](https://kiwiirc.com/) is a good web
+client if you don't already have an IRC client installed, please [Freenode](https://webchat.freenode.net/)
+has one of their own.

docs/markdown/toc.md

@@ -0,0 +1,19 @@
+####Table of Contents
+
+Introduction
+* Intro1
+
+Getting Started
+* [Configure Tvheadend](configure_tvheadend)
+
+Web Interface Guide
+
+* Access Configuration
+
+  - [Users](class/access)
+  - [Passwords](class/passwd)
+
+Appendices
+
+[About](index)
+

src/docs.c

@@ -1,5 +1,5 @@
 #include <unistd.h>
-//#include "tvh_locale.h"
+#include "docs.h"
 
 #define LANGPREF "\xff"
 #define N_(s) s

src/webui/doc_md.c

@@ -20,6 +20,7 @@
 #include "config.h"
 #include "webui.h"
 #include "http.h"
+#include "docs.h"
 
 /* */
 static int
@@ -201,12 +202,35 @@ http_markdown_class(http_connection_t *hc, const char *clazz)
   return 0;
 }
 
+/**
+ *
+ */
+static int
+http_markdown_page(http_connection_t *hc, const struct tvh_doc_page *page)
+{
+  const char **doc = page->strings;
+  const char *lang = hc->hc_access->aa_lang_ui;
+  htsbuf_queue_t *hq = &hc->hc_reply;
+
+  if (doc == NULL)
+    return HTTP_STATUS_NOT_FOUND;
+  for (; *doc; doc++) {
+    if (*doc[0] == '\xff') {
+      htsbuf_append_str(hq, tvh_gettext_lang(lang, *doc + 1));
+    } else {
+      htsbuf_append_str(hq, *doc);
+    }
+  }
+  return 0;
+}
+
 /**
  * Handle requests for markdown export.
  */
 int
 page_markdown(http_connection_t *hc, const char *remain, void *opaque)
 {
+  const struct tvh_doc_page *page;
   char *components[2];
   int nc, r;
 
@@ -221,9 +245,18 @@ page_markdown(http_connection_t *hc, const char *remain, void *opaque)
     r = http_markdown_classes(hc);
   else if (nc == 2 && !strcmp(components[0], "class"))
     r = http_markdown_class(hc, components[1]);
-  else
+  else if (nc == 1) {
+    for (page = tvh_doc_markdown_pages; page->name; page++)
+      if (!strcmp(page->name, components[0])) {
+        r = http_markdown_page(hc, page);
+        goto done;
+      }
     r = HTTP_STATUS_BAD_REQUEST;
+  } else {
+    r = HTTP_STATUS_BAD_REQUEST;
+  }
 
+done:
   if (r == 0)
     http_output_content(hc, "text/markdown");
 

src/webui/extjs.c

@@ -196,7 +196,7 @@ page_about(http_connection_t *hc, const char *remain, void *opaque)
   htsbuf_qprintf(hq, "<center>\n\
 <div class=\"about-title\">HTS Tvheadend %s</div>\n\
 <p>&copy; 2006 - 2016 Andreas \303\226man, Jaroslav Kysela, Adam Sutton, et al.</p>\n\
-<p><img src=\"docresources/tvheadendlogo.png\"></p>\n\
+<p><img src=\"static/img/logobig.png\"></p>\n\
 <p><a href=\"https://tvheadend.org\">https://tvheadend.org</a></p>\n",
     tvheadend_version);