Re: [PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support

2015-10-01 Thread Jani Nikula 
On Mon, 07 Sep 2015, Danilo Cesar Lemes de Paula  
wrote:
>  %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
> + @(which pandoc > /dev/null 2>&1) || \
> + (echo "*** To get propper documentation you need to install pandoc 
> ***";)

s/propper/proper/

This only seems to be applied to our (drm-intel) topical branch,
otherwise would've sent a patch.

BR,
Jani.



-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Re: [PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support

2015-10-01 Thread Jani Nikula 
On Mon, 07 Sep 2015, Danilo Cesar Lemes de Paula  
wrote:
>  %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
> + @(which pandoc > /dev/null 2>&1) || \
> + (echo "*** To get propper documentation you need to install pandoc 
> ***";)

s/propper/proper/

This only seems to be applied to our (drm-intel) topical branch,
otherwise would've sent a patch.

BR,
Jani.



-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support

2015-09-07 Thread Danilo Cesar Lemes de Paula 
Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current
documentation.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 54 --
 scripts/kernel-doc | 66 --
 3 files changed, 119 insertions(+), 26 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 93eff64..c1ff834 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
+MARKDOWNREADY := 
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -81,18 +83,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $<
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  \
+   set -e; 
\
+   USEMARKDOWN=""; 
\
+   FILE=`basename $@`; 
\
+   [[ "$(MARKDOWNREADY)" =~ "$${FILE}" ]] && USEMARKDOWN="-use-markdown";  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1)) $$USEMARKDOWN >$@; 
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  
\
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc > /dev/null 2>&1) || \
+   (echo "*** To get propper documentation you need to install pandoc 
***";)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -103,6 +110,10 @@ notfoundtemplate = echo "*** You have to install 
docbook-utils or xmlto ***"; \
 db2xtemplate = db2TYPE -o $(dir $@) $<
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
 
+ifneq ($(shell which pandoc >/dev/null 2>&1 && echo found),found)
+   MARKDOWNREADY := "";
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..7c6b225 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
 #define NOFUNCTION"-nofunction"
 #define NODOCSECTIONS "-no-doc-sections"
 #define SHOWNOTFOUND  "-show-not-found"
+#define USEMARKDOWN   "-use-markdown"
 
 static char *srctree, *kernsrctree;
 
 static char **all_list = NULL;
 static int all_list_len = 0;
 
+static int use_markdown = 0;
+
 static void consume_symbol(const char *sym)
 {
int i;
@@ -95,10 +98,11 @@ static void consume_symbol(const char *sym)
 
 static void usage (void)
 {
-   fprintf(stderr, "Usage: docproc {doc|depend} file\n");
+   fprintf(stderr, "Usage: docproc {doc|depend} [-use-markdown] file\n");
fprintf(stderr, "Input is read from file.tmpl. Output is sent to 
stdout\n");
fprintf(stderr, "doc: frontend when generating kernel

[PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support

2015-09-07 Thread Danilo Cesar Lemes de Paula 
Markdown support is given by calling an external tool, pandoc, for all
highlighted text on kernel-doc.

Pandoc converts Markdown text to proper Docbook tags, which will be
later translated to pdf, html or other targets.

This adds the capability of adding human-readle text highlight (bold,
underline, etc), bullet and numbered lists, simple tables, fixed-width
text (including asciiart), requiring minimal changes to current
documentation.

At this moment, pandoc is totally optional. Docbooks ready for markdown
should be added to the MARKDOWNREADY variable inside the Makefile. In
case the developer doesn't have pandoc installed, Make will throw a
warning and the documentation build will continue, generating
simple Documentation without the features brought by pandoc.

Signed-off-by: Danilo Cesar Lemes de Paula 
Cc: Randy Dunlap 
Cc: Daniel Vetter 
Cc: Laurent Pinchart 
Cc: Jonathan Corbet 
Cc: Herbert Xu 
Cc: Stephan Mueller 
Cc: Michal Marek 
Cc: linux-kernel@vger.kernel.org
Cc: linux-...@vger.kernel.org
Cc: intel-gfx 
Cc: dri-devel 
---
 Documentation/DocBook/Makefile | 25 +++-
 scripts/docproc.c  | 54 --
 scripts/kernel-doc | 66 --
 3 files changed, 119 insertions(+), 26 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 93eff64..c1ff834 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -17,6 +17,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
+MARKDOWNREADY := 
+
 include Documentation/DocBook/media/Makefile
 
 ###
@@ -81,18 +83,23 @@ XMLTOFLAGS += --skip-validation
 # The following rules are used to generate the .xml documentation
 # required to generate the final targets. (ps, pdf, html).
 quiet_cmd_docproc = DOCPROC $@
-  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
+  cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $<
 define rule_docproc
-   set -e; \
-$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)\
-$(cmd_$(1));   \
-(  \
-  echo 'cmd_$@ := $(cmd_$(1))';\
-  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  \
+   set -e; 
\
+   USEMARKDOWN=""; 
\
+   FILE=`basename $@`; 
\
+   [[ "$(MARKDOWNREADY)" =~ "$${FILE}" ]] && USEMARKDOWN="-use-markdown";  
\
+$(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';)
\
+$(cmd_$(1)) $$USEMARKDOWN >$@; 
\
+(  
\
+  echo 'cmd_$@ := $(cmd_$(1))';
\
+  echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`;  
\
 ) > $(dir $@).$(notdir $@).cmd
 endef
 
 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
+   @(which pandoc > /dev/null 2>&1) || \
+   (echo "*** To get propper documentation you need to install pandoc 
***";)
$(call if_changed_rule,docproc)
 
 # Tell kbuild to always build the programs
@@ -103,6 +110,10 @@ notfoundtemplate = echo "*** You have to install 
docbook-utils or xmlto ***"; \
 db2xtemplate = db2TYPE -o $(dir $@) $<
 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
 
+ifneq ($(shell which pandoc >/dev/null 2>&1 && echo found),found)
+   MARKDOWNREADY := "";
+endif
+
 # determine which methods are available
 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
use-db2x = db2x
diff --git a/scripts/docproc.c b/scripts/docproc.c
index e267e621..7c6b225 100644
--- a/scripts/docproc.c
+++ b/scripts/docproc.c
@@ -73,12 +73,15 @@ FILELINE * docsection;
 #define NOFUNCTION"-nofunction"
 #define NODOCSECTIONS "-no-doc-sections"
 #define SHOWNOTFOUND  "-show-not-found"
+#define USEMARKDOWN   "-use-markdown"
 
 static char *srctree, *kernsrctree;
 
 static char **all_list = NULL;
 static int all_list_len = 0;
 
+static int use_markdown = 0;
+
 static void consume_symbol(const char *sym)
 {
int i;
@@ -95,10 +98,11 @@ static void consume_symbol(const char *sym)
 
 static void usage (void)
 {
-   fprintf(stderr, "Usage: