kumakichi / protoc-gen-docbook Goto Github PK

What steps will reproduce the problem?
1. See attached test.proto showing a nested message and enum.
2. See resultant test.docbook output.


What is the expected output? What do you see instead?

If you look at the sections in the docbook output you see that the nested 
properties for a message generate output which is nested in terms of section 
depth but not in terms of markup containers.  Grepping for sect in that docbook 
shows this:

<sect1><title> File: test.proto</title>
<sect3><title> Message: OuterMessage</title>
</sect3>
<sect4><title> Message: OuterMessage.InnerMessage</title>
</sect4>
<sect5><title> Enum: OuterMessage.InnerMessage.InnerEnum</title>
</sect5>
</sect1>

It really ought to show this:

<sect1><title> File: test.proto</title>
<sect2><title> Message: OuterMessage</title>
</sect2>
<sect3><title> Message: OuterMessage.InnerMessage</title>
<sect4><title> Enum: OuterMessage.InnerMessage.InnerEnum</title>
</sect4>
</sect3>
</sect2>
</sect1>

If you look at the docbook documentation it is clearly illegal to place a 
sect(N) inside any container except sect(N-1):

http://www.docbook.org/tdg/en/html/sect2.html


What version of the product are you using? On what operating system?

protoc-gen-docbook 0.3.0 release on Linux.


Please provide any additional information below.

I spent some time instrumenting docbook_generator.cc.  It appears that closing 
of sections is married to the closing of field tables for a message and that 
sub-message definitions are output *after* the section is closed.  

What steps will reproduce the problem?
1. create a .proto file containing an enum whose value starts at 1 then skips 
some values.  E.g.: 1,2,3,4,5,10,11,12,13,14,15

What is the expected output? I expect the Value column to show correct values.  
It does not.

What do you see instead?  I see the following in the Value column for my enum: 
0,1,2,3,4,5,6,7,8,9,10

What version of the product are you using? protoc-gen-docbook 0.3.1 full bundle 
- Windows Binary

On what operating system? Windows 7

Please provide any additional information below.

Protobuf 2.5 has added support for Javadoc comments.

This is a nice feature but nowhere as nice a your DocBook plugin.
Actually we would very much like to use both.

The standard protobuf compiler when generating the .java files will put Javadoc 
comments like this


/**
  * <pre>Here is a multi-line 
  * comment.
  * </pre>
  */
class Foo(.....) {
}

This preserves line wrapping and is actually a very good idea. I wish there was 
a way to make this plugin do the same.


Anyway, this report is not about Java, it is really just mentioned here for 
comparison.

Currently, protoc-gen-docbook can be cross-compiled under GCC. However, the 
current packaging and deployment mechanism are oriented toward Windows users. 

To fix this, we need the following:
 * Configure and Makefile
 * Need to port Run.bat batch script into shell script.
 * Need new tutorials for Linux and OSX users.

Perhaps this is a small matter.

(this is more of a how-to than a bug report or a new feature request)


I'm not a big fan of the use of serif fonts (e.g. Times Roman) for anything 
that is supposed to be used online. You don't see many websites or technical 
documentation using it.

Example: Javadoc by default uses Arial (which is a sans serif font). 
The plugin uses Apache FOP which in turn uses (by default) font family 
"sans-serif" for titles and "serif" for body. In other words it mixes the two ! 
 Not my cup of tea.


You can customize this in the run.bat file supplied with the plugin.

Inside this file you'll find a call to "fop.bat" that will look like this:

cmd /c %fop_path%\fop.bat ^
-xml %docbook_input% ^
-xsl %fop_path%\docbook-xsl-1.78.0\fo\docbook.xsl ^
-pdf %pdf_output% ^
-param page.orientation landscape ^
-param paper.type A4


Simply change it to:


cmd /c %fop_path%\fop.bat ^
-xml %docbook_input% ^
-xsl %fop_path%\docbook-xsl-1.78.0\fo\docbook.xsl ^
-pdf %pdf_output% ^
-param page.orientation landscape ^
-param paper.type A4 ^
-param body.font.family sans-serif


(you may note that I also changed the "paper.type" from "USLetter" to "A4"  ... 
which of course has nothing to do with the matter).

What steps will reproduce the problem?
1. Installed protobuf 2.5.0 from source:
$ tar xvf protobuf-2.5.0.tar.bz2 
$ cd protobuf-2.5.0/
$ ./configure --prefix=/usr
$ make -j 4
$ sudo make install

2. Checked out 0.3.0 tag (same results with current trunk):
svn checkout http://protoc-gen-docbook.googlecode.com/svn/tags/release/0.3.0 
protoc-gen-docbook-0.3.0

3. Patched linux makefile linux/src/subdir.mk to update 
"external/includes/protobuf-2.5.0rc1" to "external/includes/protobuf-2.5.0/" to 
match the checked out path

4. Built ...:
$ cd protoc-gen-docbook-0.3.0/linux/
$ make clean; make

5. Attempted to generate the example-addressbook included:
$ cd ../deploy/example-addressbook/
$ protoc -I/usr/include --proto_path=. addressbook.proto 
--plugin=../../linux/protoc-gen-docbook --docbook_out=.
$ fop -xml docbook_out.xml -xsl 
/usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl -pdf 
docbook_out.pdf -param page.orientation landscape -param paper.type USletter

6. Checked in both the xml and pdf output, no comments from the .proto file 
made it into the description column ... see attached files.

The base OS is Ubuntu 10.04.4.

I've attached the modified subdir.mk and the output xml & pdf files. Please let 
me know if I can run any experiments (verbose mode etc ...). The tool looks 
very helpful, I'd love to get it running ...

Thanks for your work!
--Matt Hughes

I see that docbook.properties allows preserve_comment_line_breaks but what I 
would like is to ignore normally (so that proper wrapping etc occurs in the 
generated pdf) however sometimes I would like an explicit line break especially 
for things like bullet lists, etc.

E.g.: 

// Comment, bla bla, bla
// NOTES:
//  1) bla bla bla
//  2) bla bla bla

Just comes out in the pdf as:

Comment, bla bla, bla NOTES:  1) bla bla bla  2) bla bla bla

It would be nice to have some formatting abilities.

What steps will reproduce the problem?
1. .proto with two messages, where the second is extends of first.
2. Generate the xml (data is missing here, so not a problem with PDF)

What is the expected output? What do you see instead?
The output has each separate message, but no reference or text to indicate that 
the extending message will have the parent's attributes in the message.


What version of the product are you using? On what operating system?
0.3.1 Full. Windows. 


Please provide any additional information below.