[Qemu-devel] [RFC] Documentation: Create qemu-doc.html with makeinfo instead of html2texi

[Qemu-devel] [RFC] Documentation: Create qemu-doc.html with makeinfo instead of html2texi

[Stefan Weil]

Hello,

today, html documentation is created using texi2html.

makeinfo can also create html output which looks different.
I think it looks better, but try it yourself:

texi2html (old):
http://wiki.qemu.org/download/qemu-doc.html

makeinfo (new):
http://www.weilnetz.de/qemu-doc.html (single file)
http://www.weilnetz.de/qemu-doc/ (split in many files)

The new qemu-doc.html is smaller than the old one,
so it loads a little faster.

If the new format is accepted, I can provide a patch.

Regards,
Stefan Weil

Re: [Qemu-devel] [RFC] Documentation: Create qemu-doc.html with makeinfo instead of html2texi

[Aurelien Jarno]

On Fri, Feb 12, 2010 at 11:43:28AM +0100, Stefan Weil wrote:
> Hello,
> 
> today, html documentation is created using texi2html.
> 
> makeinfo can also create html output which looks different.
> I think it looks better, but try it yourself:
> 
> texi2html (old):
> http://wiki.qemu.org/download/qemu-doc.html
> 
> makeinfo (new):
> http://www.weilnetz.de/qemu-doc.html (single file)
> http://www.weilnetz.de/qemu-doc/ (split in many files)
> 
> The new qemu-doc.html is smaller than the old one,
> so it loads a little faster.
> 
> If the new format is accepted, I can provide a patch.
> 

I agree the makeinfo single file version looks better, but it would be 
nice to have the opinion of other developers.

-- 
Aurelien Jarno                          GPG: 1024D/F1BCDB73
aurelien@aurel32.net                 http://www.aurel32.net

[Qemu-devel] [PATCH] Documentation: Modify rule for html output (better looking output format)

[Stefan Weil]

To create html output from texi input, texi2html was used.
Output from makeinfo looks cleaner, so replace the old rule
and use makeinfo now.

For those who want to use their own variant of html output,
the macros MAKEINFO and MAKEINFOFLAGS allow customisation.
Option "-I ." is not needed (the current directory is
searched by default), so remove it.

Please note that the build requirements changed, too:
makeinfo is required for doc builds.
texi2html is no longer used.

Signed-off-by: Stefan Weil <weil@mail.berlios.de>
---
 Makefile  |    7 +++++--
 configure |    2 +-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 1f6c3ea..bf2cef2 100644
--- a/Makefile
+++ b/Makefile
@@ -230,15 +230,18 @@ cscope:
 	cscope -b
 
 # documentation
+MAKEINFO=makeinfo
+MAKEINFOFLAGS=--no-headers --no-split --number-sections
 TEXIFLAG=$(if $(V),,--quiet)
 %.dvi: %.texi
 	$(call quiet-command,texi2dvi $(TEXIFLAG) -I . $<,"  GEN   $@")
 
 %.html: %.texi
-	$(call quiet-command,texi2html -I=. -monolithic -number $<,"  GEN   $@")
+	$(call quiet-command,$(MAKEINFO) $(MAKEINFOFLAGS) --html $< -o $@, \
+	"  GEN   $@")
 
 %.info: %.texi
-	$(call quiet-command,makeinfo -I . $< -o $@,"  GEN   $@")
+	$(call quiet-command,$(MAKEINFO) $< -o $@,"  GEN   $@")
 
 %.pdf: %.texi
 	$(call quiet-command,texi2pdf $(TEXIFLAG) -I . $<,"  GEN   $@")
diff --git a/configure b/configure
index b4db650..19eb620 100755
--- a/configure
+++ b/configure
@@ -1759,7 +1759,7 @@ fi
 
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has texi2html && has pod2man; then
+  if has makeinfo && has pod2man; then
     docs=yes
   else
     if test "$docs" = "yes" ; then
-- 
1.7.0

Re: [Qemu-devel] [RFC] Documentation: Create qemu-doc.html with makeinfo instead of html2texi

[Stefan Weil]

Aurelien Jarno schrieb:
> On Fri, Feb 12, 2010 at 11:43:28AM +0100, Stefan Weil wrote:
>> Hello,
>>
>> today, html documentation is created using texi2html.
>>
>> makeinfo can also create html output which looks different.
>> I think it looks better, but try it yourself:
>>
>> texi2html (old):
>> http://wiki.qemu.org/download/qemu-doc.html
>>
>> makeinfo (new):
>> http://www.weilnetz.de/qemu-doc.html (single file)
>> http://www.weilnetz.de/qemu-doc/ (split in many files)
>>
>> The new qemu-doc.html is smaller than the old one,
>> so it loads a little faster.
>>
>> If the new format is accepted, I can provide a patch.
>>
>
> I agree the makeinfo single file version looks better, but it would be
> nice to have the opinion of other developers.
>

Antony Liguori agrees, too.
So the minimum of 3 positive votes was reached, and I sent the patch :-)

Regards,
Stefan

Re: [Qemu-devel] [RFC] Documentation: Create qemu-doc.html with makeinfo instead of html2texi

[Andreas Färber]

Hello,

Am 04.03.2010 um 22:25 schrieb Stefan Weil:

> Aurelien Jarno schrieb:
>> On Fri, Feb 12, 2010 at 11:43:28AM +0100, Stefan Weil wrote:
>>> today, html documentation is created using texi2html.
>>>
>>> makeinfo can also create html output which looks different.
>>> I think it looks better, but try it yourself:
>>>
>>> texi2html (old):
>>> http://wiki.qemu.org/download/qemu-doc.html
>>>
>>> makeinfo (new):
>>> http://www.weilnetz.de/qemu-doc.html (single file)
>>> http://www.weilnetz.de/qemu-doc/ (split in many files)
>>>
>>> The new qemu-doc.html is smaller than the old one,
>>> so it loads a little faster.
>>>
>>> If the new format is accepted, I can provide a patch.
>>>
>>
>> I agree the makeinfo single file version looks better, but it would  
>> be
>> nice to have the opinion of other developers.

I've recently been seeing texi2html problems on OSX:

   GEN   qemu-doc.html
Unknown open() mode ':encoding(utf-8-strict)' at /usr/bin/texi2html  
line 11111.
make: *** [qemu-doc.html] Error 2

Short of time, I didn't find a quick solution (no mention of utf-8- 
strict anywhere?) and just disabled it.
If makeinfo improves that, I'd certainly welcome it.

Andreas

> Antony Liguori agrees, too.
> So the minimum of 3 positive votes was reached, and I sent the  
> patch :-)
>
> Regards,
> Stefan