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 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.

> > 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