[BRLTTY] documentation issues

[Samuel Thibault]

Hello,

Rich Morin, on Mon 04 Jul 2016 11:07:12 -0700, wrote:
> The "Documentation" page (http://mielke.cc/brltty/documentation.html)
> contains a link (The BrlAPI Programmers' Reference) to:
> 
>   BrlAPI  1.0
>   http://mielke.cc/brltty/doc/BrlAPIref/index.html
> 
> The page in question appears to be rather dated, even though it was
> generated by Doxygen.  Also, all of the img (image) links are broken.

Dave, could you have a look?

> The link from the "How to make applications accessible?" page
> (http://brl.thefreecat.org) for the BrlAPI "reference manual"
> (on http://brl.thefreecat.org) gets a 404 (Not Found) error:

Fixed, thanks!

> I dislike reading manuals from a computer screen, but I couldn't find
> an easy way to print the manual.  Am I missing something?

Dave, perhaps we could also generate a pdf version? (linuxdoc supports
emitting a .tex file which we could compile)

> FWIW, a "text" version of the manual is available at:
> 
>   http://mielke.cc/brltty/doc/Manual-BrlAPI/English/BrlAPI.txt
> 
> However, it is essentially unusable, due to peculiarities such as:
> 
>   11..  IInnttrroodduuccttiioonn
>   _B_r_l_A_P_I is a service ...

Ah, the old dumb overstrike trick...
Dave, could you apply the attached patch to get rid of them?

> ## Updates?
> 
> The only version of the manual I could find is almost a decade old:

Yes, the use of BrlAPI hasn't really changed since then.

>   The current production version of BrlAPI is 0.6.5 (June 28, 2016).

These were only minor updates, which don't change the application side.

> # BRLTTY Download page
> 
> The download page contains no descriptions of the downloadable files.
> The extensions (eg, apk, exe, rpm, tar.gz, tar.xz, zip) hint at the
> file formats, but I see no indication of the contents.  For example,
> which archives subsume which other ones?

I'll leave that to Dave too.

Samuel
-------------- next part --------------
diff --git a/document.mk b/document.mk
index 3d2e81e..1779f37 100644
--- a/document.mk
+++ b/document.mk
@@ -27,7 +27,7 @@ txt: $(DOCUMENT_NAME).txt
 html: html.made
 
 $(DOCUMENT_NAME).txt: $(SRC_DIR)/$(DOCUMENT_NAME).sgml
-	$(SETLOCALE) linuxdoc -B txt -l $(DOCUMENT_LANGUAGE) -c latin $<
+	$(SETLOCALE) linuxdoc -B txt -f -l $(DOCUMENT_LANGUAGE) -c latin $<
 	sed -e 's/\x1B\[[0-9][0-9]*m//g' -i $@
 
 html.made: $(SRC_DIR)/$(DOCUMENT_NAME).sgml