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

[Matt Wilson <msw@xxxxxxxxxx>]

On Tue, Jul 31, 2012 at 08:34:59AM -0700, Matt Wilson wrote:
> On Tue, Jul 31, 2012 at 01:29:03AM -0700, Ian Campbell wrote:
> > 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?
> 
> I'm not sure how much the markdown can be tidied for constructs like:
> 
> ### apic
> > `= summit | bigsmp | default`
> 
> Override Xen's logic for choosing the APIC driver.  By default, if
> there are more than 8 CPUs, Xen will switch to `bigsmp` over
> `default`.
> 
> ### allow\_unsafe
> > `= <boolean>`
> 
> > Default: `false`
> 
> Force boot on potentially unsafe systems. By default Xen will refuse
> to boot on systems with the following errata:
> 
> * AMD Erratum 121. Processors with this erratum are subject to a guest
>   triggerable Denial of Service. Override only if you trust all of
>   your PV guests.
> 
> When processed as I propose, it looks like:
> 
>   apic
> 
>      = summit | bigsmp | default
> 
>    Override Xen's logic for choosing the APIC driver. By default, if there
>    are more than 8 CPUs, Xen will switch to bigsmp over default.
> 
>   allow_unsafe
> 
>      = <boolean>
> 
>      Default: false
> 
>    Force boot on potentially unsafe systems. By default Xen will refuse to
>    boot on systems with the following errata:
>      * AMD Erratum 121. Processors with this erratum are subject to a
>        guest triggerable Denial of Service. Override only if you trust all
>        of your PV guests.
> 
> 
> > 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?
> 
> I generally don't have lynx installed on my production machines.

Ian,

Any further concerns?

Matt

> > > 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?
> 
> Oops, sorry. This is bogus. I'll resubmit with it removed.
> 
> Matt
> 
> > >  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

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