Re: [Xen-devel] [PATCH DOCDAY] use lynx to produce better formatted text documentation from markdown

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Mon, 2012-07-30 at 20:33 +0100, Matt Wilson wrote:
> Markdown, while easy to read and write, isn't the most consumable
> format for users reading documentation on a terminal. This patch uses
> lynx to format markdown produced HTML into text files.

The markdown syntax is supposed to be readable as plain text too, if
there are particular instances where this is not the case perhaps we can
tidy them up with that in mind?

Why wouldn't you just run lynx on the generated .html instead of less on
the generated .txt if you wanted something a bit better formatted?

> 
> Signed-off-by: Matt Wilson <msw@xxxxxxxxxx>
> 
> diff -r c3a6e679bdfa -r ef1271aef866 docs/Docs.mk
> --- a/docs/Docs.mk    Mon Jul 30 19:04:59 2012 +0000
> +++ b/docs/Docs.mk    Mon Jul 30 19:33:41 2012 +0000
> @@ -10,3 +10,4 @@ POD2TEXT    := pod2text
>  DOT          := dot
>  NEATO                := neato
>  MARKDOWN     := markdown
> +LYNX         := lynx
> diff -r c3a6e679bdfa -r ef1271aef866 docs/Makefile
> --- a/docs/Makefile   Mon Jul 30 19:04:59 2012 +0000
> +++ b/docs/Makefile   Mon Jul 30 19:33:41 2012 +0000
> @@ -103,7 +103,16 @@ html/%.html: %.markdown
>  
>  html/%.txt: %.txt
>       @$(INSTALL_DIR) $(@D)
> -     cp $< $@
> +     @set -e ; \
> +     if which $(MARKDOWN) >/dev/null 2>&1 && \
> +             which $(LYNX) >/dev/null 2>&1 ; then \
> +             echo "Running markdown to generate $*.txt ... "; \
> +             $(MARKDOWN) $< | lynx -dump -stdin > $@.tmp ; \
> +             $(call move-if-changed,$@.tmp,$@) ; \
> +     else \
> +             echo "markdown or lynx not installed; just copying $<."; \
> +             cp $< $@; \
> +     fi

Does formatting a non-markdown .txt file like this produce reasonable
results for all the random ASCII formatting used under misc?
 
>  html/man/%.1.html: man/%.pod.1 Makefile
>       $(INSTALL_DIR) $(@D)
> @@ -131,9 +140,17 @@ txt/%.txt: %.txt
>       $(call move-if-changed,$@.tmp,$@)
>  
>  txt/%.txt: %.markdown
> -     $(INSTALL_DIR) $(@D)
> -     cp $< $@.tmp
> -     $(call move-if-changed,$@.tmp,$@)
> +     @$(INSTALL_DIR) $(@D)
> +     @set -e ; \
> +     if which $(MARKDOWN) >/dev/null 2>&1 && \
> +             which $(LYNX) >/dev/null 2>&1 ; then \
> +             echo "Running markdown to generate $*.txt ... "; \
> +             $(MARKDOWN) $< | lynx -dump -stdin > $@.tmp ; \
> +             $(call move-if-changed,$@.tmp,$@) ; \
> +     else \
> +             echo "markdown or lynx not installed; just copying $<."; \
> +             cp $< $@; \
> +     fi
>  
>  txt/man/%.1.txt: man/%.pod.1 Makefile
>       $(INSTALL_DIR) $(@D)
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@xxxxxxxxxxxxx
> http://lists.xen.org/xen-devel



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel