tweak make htmldocs (nochunks and better index).

PATCH In review Rob Landley 3 participants 5 messages May 29, 2007 – May 30, 2007 Documentation

lore

Share & tools

lore

Rob Landley

author

2007-05-29 19:28 UTC #0 lore raw

PATCH 1/1 tweak make htmldocs (nochunks and better index).

Signed-off-by Rob Landley <[email protected]>

A) The "xmtml-nochunks" version of "make htmldocs" is easier to print.

B) Update the generated index.html to use the html <title> as a description for each file it links to.

Documentation/DocBook/Makefile +6 -3

@@ -141,9 +141,12 @@
 		   cat $(HTML) >> $(main_idx)
 
 quiet_cmd_db2html = HTML   $@
-      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
-		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
-        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
+      cmd_db2html = xmlto xhtml-nochunks $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
+		NAME='$(patsubst %.html,%,$(notdir $@))'; \
+		echo -n "<p><a HREF=\"$$NAME/$$NAME.html\">$$NAME</a>" > $@ ; \
+		sed -nre 's@.*<title>(.*)</title>.*@\1@p' \
+			"Documentation/DocBook/$$NAME/$$NAME.html" >> $@ ; \
+		echo '<\p>' >> $@
 
 %.html:	%.xml
 	@(which xmlto > /dev/null 2>&1) || \

Randy Dunlap

2007-05-30 04:13 UTC #1 lore raw

Quoted 18 lines · On Tue, 29 May 2007 15:28:33 -0400 Rob Landley wrote:

Signed-off-by Rob Landley <[email protected]>
A) The "xmtml-nochunks" version of "make htmldocs" is easier to print.
B) Update the generated index.html to use the html <title> as a description for each file it links to.
--
Documentation/DocBook/Makefile +0 -3
@@ -141,9 +141,12 @@
 		   cat $(HTML) >> $(main_idx)
 
 quiet_cmd_db2html = HTML   $@
-      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
-		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
-        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@

Documentation/DocBook/Makefile

Quoted 10 lines

Documentation/DocBook/Makefile +6 -1

+      cmd_db2html = xmlto xhtml-nochunks $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
+		NAME='$(patsubst %.html,%,$(notdir $@))'; \
+		echo -n "<p><a HREF=\"$$NAME/$$NAME.html\">$$NAME</a>" > $@ ; \
+		sed -nre 's@.*<title>(.*)</title>.*@\1@p' \
+			"Documentation/DocBook/$$NAME/$$NAME.html" >> $@ ; \
+		echo '<\p>' >> $@
 
 %.html:	%.xml
 	@(which xmlto > /dev/null 2>&1) || \
-

What is <\p> supposed to do?

Here's what I see in index.html (beginning lines of it):

Linux Kernel HTML Documentation
Kernel Version: 2.6.22-rc3

deviceiobookBus-Independent Device Accesses <\p>

filesystemsLinux Filesystems API <\p>

gadgetUSB Gadget API for Linux <\p>

genericirqLinux generic IRQ handling <\p>

kernel-apiThe Linux Kernel API <\p>

kernel-hackingUnreliable Guide To Hacking The Linux Kernel <\p>

kernel-lockingUnreliable Guide To Locking <\p>

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Rob Landley

author

2007-05-30 18:48 UTC #2 lore raw

Quoted 1 line · Randy Dunlap

What is <\p> supposed to do?

Sorry, typo. Should be </p> instead. My bad.

As to what it does in a larger sense, "make the xml people happy". Closing parentheses tags make the various xhtml validators shut up. The main difference between xhtml and html is that you close all the tags you open. I can yank it if people prefer it that way.

Quoted 6 lines

Here's what I see in index.html (beginning lines of it):
Linux Kernel HTML Documentation
Kernel Version: 2.6.22-rc3
deviceiobookBus-Independent Device Accesses <\p>

Yeah, that's screwed up. (It looked fine in Konqueror. :) *rummage*...

Here's an updated patch. This time I checked that it looked ok in Firefox too:

Documentation/DocBook/Makefile +6 -3

@@ -141,9 +141,12 @@
 		   cat $(HTML) >> $(main_idx)
 
 quiet_cmd_db2html = HTML   $@
-      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
-		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
-        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
+      cmd_db2html = xmlto xhtml-nochunks $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
+		NAME='$(patsubst %.html,%,$(notdir $@))'; \
+		echo -n "<p><a HREF=\"$$NAME/$$NAME.html\">$$NAME</a> - " >$@; \
+		sed -nre 's@.*<title>(.*)</title>.*@\1@p' \
+			"Documentation/DocBook/$$NAME/$$NAME.html" >> $@ ; \
+		echo '</p>' >> $@
 
 %.html:	%.xml
 	@(which xmlto > /dev/null 2>&1) || \

Rob

Randy Dunlap

2007-05-30 19:30 UTC #3 lore raw

Quoted 15 lines · On Wed, 30 May 2007 14:47:41 -0400 Rob Landley wrote:

Quoted 1 line · Randy Dunlap
What is <\p> supposed to do?
Sorry, typo. Should be </p> instead. My bad.
As to what it does in a larger sense, "make the xml people happy". Closing parentheses tags make the various xhtml validators shut up. The main difference between xhtml and html is that you close all the tags you open. I can yank it if people prefer it that way.
Quoted 5 lines
Here's what I see in index.html (beginning lines of it):
Linux Kernel HTML Documentation
Kernel Version: 2.6.22-rc3

Quoted 6 lines

Quoted 1 line
deviceiobookBus-Independent Device Accesses <\p>
Yeah, that's screwed up. (It looked fine in Konqueror. :) *rummage*...
Here's an updated patch. This time I checked that it looked ok in Firefox too:

Yes, /me too. Thanks.

I still disagree on the use of "nochunks" though.

Quoted 19 lines

Documentation/DocBook/Makefile +6 -3

@@ -141,9 +141,12 @@
 		   cat $(HTML) >> $(main_idx)
 
 quiet_cmd_db2html = HTML   $@
-      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
-		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
-        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
+      cmd_db2html = xmlto xhtml-nochunks $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
+		NAME='$(patsubst %.html,%,$(notdir $@))'; \
+		echo -n "<p><a HREF=\"$$NAME/$$NAME.html\">$$NAME</a> - " >$@; \
+		sed -nre 's@.*<title>(.*)</title>.*@\1@p' \
+			"Documentation/DocBook/$$NAME/$$NAME.html" >> $@ ; \
+		echo '</p>' >> $@
 
 %.html:	%.xml
 	@(which xmlto > /dev/null 2>&1) || \

Quoted 1 line

Rob

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Randy Dunlap

2007-05-30 05:05 UTC #4 lore raw

In reply to Rob Landley

Quoted 3 lines · On Tue, 29 May 2007 15:28:33 -0400 Rob Landley wrote:

Signed-off-by Rob Landley <[email protected]>
A) The "xmtml-nochunks" version of "make htmldocs" is easier to print.

and makes it darn near impossible to print one page or function if that's all that someone is interested in.

I'd prefer to leave the html output in separate files and use pdf or ps output for printing entire files. But that's just my take on it.

Quoted 12 lines

B) Update the generated index.html to use the html <title> as a description for each file it links to.
--
Documentation/DocBook/Makefile +0 -1
@@ -141,9 +141,12 @@
 		   cat $(HTML) >> $(main_idx)
 
 quiet_cmd_db2html = HTML   $@
-      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \

Documentation/DocBook/Makefile line 151

Quoted 10 lines

Documentation/DocBook/Makefile +6 -2

-		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
-        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
+      cmd_db2html = xmlto xhtml-nochunks $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
+		NAME='$(patsubst %.html,%,$(notdir $@))'; \
+		echo -n "<p><a HREF=\"$$NAME/$$NAME.html\">$$NAME</a>" > $@ ; \
+		sed -nre 's@.*<title>(.*)</title>.*@\1@p' \
+			"Documentation/DocBook/$$NAME/$$NAME.html" >> $@ ; \
+		echo '<\p>' >> $@
 %.html:	%.xml
 	@(which xmlto > /dev/null 2>&1) || \

(repeating due to email bounced/rejected when from @oracle.com:)

What is <\p> supposed to do?

Here's what I see in index.html (beginning lines of it):

Linux Kernel HTML Documentation
Kernel Version: 2.6.22-rc3

deviceiobookBus-Independent Device Accesses <\p>

filesystemsLinux Filesystems API <\p>

gadgetUSB Gadget API for Linux <\p>

genericirqLinux generic IRQ handling <\p>

kernel-apiThe Linux Kernel API <\p>

kernel-hackingUnreliable Guide To Hacking The Linux Kernel <\p>

kernel-lockingUnreliable Guide To Locking <\p>

---
so it looks like it could use a space after the short name/before the long name/title, and fix the <\p>.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***