Opened 7 years ago

Closed 7 years ago

#3006 closed task (fixed)

Import datasource design documentation into BIND 10 git repo

Reported by: muks Owned by: muks
Priority: medium Milestone: Sprint-20130709
Component: documentation Version:
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DNS Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 2.42 Internal?: no

Description

The data source design documentation is on the wiki currently. In today's team meeting, we have decided to import this documentation into the BIND 10 git repo where it can be maintained.

We will use asciidoc for the text, and PlantUML for the UML diagrams.

Subtickets

Change History (11)

comment:1 Changed 7 years ago by muks

  • Milestone changed from New Tasks to Sprint-20130625
  • Owner set to muks
  • Status changed from new to assigned

I am assigning it to myself as I have done some initial work for it. I'll push this to the trac3006 branch shortly. It'll take a few hours to finish converting all the diagrams, and I plan to do this tomorrow.

comment:2 Changed 7 years ago by muks

  • Owner changed from muks to UnAssigned
  • Status changed from assigned to reviewing

Putting it to review.

You will need asciidoc and PlantUML to be installed before running configure. On Fedora 18, it's as simple as:

yum install asciidoc plantuml

I don't know about other distros yet.

Pre-rendered output is here:
https://staff.banu.com/~muks/tmp/datasrc/

The class diagram is a bit sucky. In hindsight, it seems automatic placement (graphviz) is not so great for class diagrams. We can fix that later.

comment:3 Changed 7 years ago by vorner

  • Owner changed from UnAssigned to vorner

comment:4 Changed 7 years ago by vorner

  • Owner changed from vorner to muks

Hello

I agree that the class diagram might need some improvements. For one, the original one had layers (which seemed very useful) that are lost in this one.

Distcheck fails, with:

make[5]: *** No rule to make target `overview.png', needed by `all'.  Stop.
make[5]: Entering directory `/tmp/bind10/bind10-2/bind10-20130529/_build/doc/design/datasrc'

I think we don't want to require these tools on normal user's system to compile the sources. If one of the tools is not ready, it will reject compilation. We don't compile man pages if docbook is not available, I think the same approach would be reasonable for developer documentation. Especially with the plantuml, which is not available as package for gentoo (and I see reasons why their ebuild they provide on the wiki page was not accepted).

What is a2x? Why is it mentioned in both rules in the makefile?

Is this generic make syntax, or GNU extension?

BUILT_SOURCES = \
	$(UML_FILES:.txt=.png) \
	$(TEXT_FILES:.txt=.html)

Are the diagram sources written by hand, or some tool helps with them? Writing the formatted text is easy, but these seem rather more complex.

I didn't read the text thoroughly, but I guess it is the same one as from Jinmei.

comment:5 Changed 7 years ago by jreed

The generated html docs look nice, but we need to use a single tool -- we already decided on doxygen. So should we integrate like doc/devel/02-dhcp.dox http://bind10.isc.org/docs/developers/cpp/d5/ded/dhcp4.html or http://bind10.isc.org/docs/developers/cpp/d3/d2f/dns.html doc/devel/01-dns.dox ?

comment:6 follow-up: Changed 7 years ago by muks

  • Owner changed from muks to vorner

Hi Michal

Replying to vorner:

Hello

I agree that the class diagram might need some improvements. For one,
the original one had layers (which seemed very useful) that are lost
in this one.

True. There are other conversion tools such as umlgraph. Maybe we can
investigate them. For now, I guess something is better than no class
diagram.

Distcheck fails, with:

make[5]: *** No rule to make target `overview.png', needed by `all'.  Stop.
make[5]: Entering directory `/tmp/bind10/bind10-2/bind10-20130529/_build/doc/design/datasrc'

I think we don't want to require these tools on normal user's system
to compile the sources. If one of the tools is not ready, it will
reject compilation. We don't compile man pages if docbook is not
available, I think the same approach would be reasonable for developer
documentation. Especially with the plantuml, which is not available
as package for gentoo (and I see reasons why their ebuild they provide
on the wiki page was not accepted).

This has been taken into account and dummy files are generated in this
case. We also use the devel make target now, just like in the
upper-level directories.

The design documentation is not installed.

What is a2x? Why is it mentioned in both rules in the makefile?

a2x is a tool that comes with asciidoc. I had initially used this to
generate the HTML output (as it generates a more plain looking HTML),
but standard asciidoc looked better and that was picked in the end.

Is this generic make syntax, or GNU extension?

BUILT_SOURCES = \
	$(UML_FILES:.txt=.png) \
	$(TEXT_FILES:.txt=.html)

I am not sure. Maybe we should put this branch through the builders and
see what happens.

Are the diagram sources written by hand, or some tool helps with them?
Writing the formatted text is easy, but these seem rather more
complex.

They have been written by hand.

They are rather simple actually. It looks complicated because there are
so many instructions. But they are rather a set of sequential
instructions, just bulky. Personally, I prefer that we code it up
manually (so that the text is as readable as it can be) and not using a
visual tool, but I guess both ways is fine as long as it's maintainable.

I didn't read the text thoroughly, but I guess it is the same one as
from Jinmei.

Nod.

Hi Jeremy

Replying to jreed:

The generated html docs look nice, but we need to use a single tool --
we already decided on doxygen.

We decided on using asciidoc during the team meeting call. There are
already several docs in the docs/design/ sub-directory which use
asciidoc (and some more in branches that will be merged).

However, I agree it is good to be consistent and use a single tool where
possible. But currently the Doxygen design documentation seems in bad
shape. We should first clean it up and make it straightforward to add
new content. Using Doxygen is outside the scope of our initial
decisions to use asciidoc for this ticket which has already been
implemented, so let's create further tickets for this. The main goal of
this ticket was to get the documentation in the repo so it can be
maintained.

comment:7 in reply to: ↑ 6 ; follow-ups: Changed 7 years ago by vorner

  • Owner changed from vorner to muks

Hello

Replying to muks:

This has been taken into account and dummy files are generated in this
case. We also use the devel make target now, just like in the
upper-level directories.

The design documentation is not installed.

Hmm. I think either one of these changes would suffice, but both is unexpected. I mean, if I want to compile the software, I usually don't require the development documentation, so it being skipped is OK and what I want. But if I actually ask to generate the development documentation explicitly, by make devel, then it should probably fail if it can't be fulfilled, not create dummy files.

Also, it looks awkward to put text into a png image (and they don't show at all in the document, if asciidoc is installed and the plantuml isn't). What about placing a dummy png file there (containing the text as image) and copy it to the target one instead of echoing a text there?

Is this generic make syntax, or GNU extension?

BUILT_SOURCES = \
	$(UML_FILES:.txt=.png) \
	$(TEXT_FILES:.txt=.html)

I am not sure. Maybe we should put this branch through the builders and
see what happens.

That could work. I also think using $(patsubst $(UML_FILES),%.txt,%.png) should work (I believe that one is standard), I don't know about this.

Are the diagram sources written by hand, or some tool helps with them?
Writing the formatted text is easy, but these seem rather more
complex.

They have been written by hand.

They are rather simple actually. It looks complicated because there are
so many instructions. But they are rather a set of sequential
instructions, just bulky. Personally, I prefer that we code it up
manually (so that the text is as readable as it can be) and not using a
visual tool, but I guess both ways is fine as long as it's maintainable.

I don't know. I did write some postscript images for my thesis. But I find it easier to draw them often.

Jinmei must have used something to make his, maybe we could just use that? And import his images as they are?

Replying to jreed:

The generated html docs look nice, but we need to use a single tool --
we already decided on doxygen.

We decided on using asciidoc during the team meeting call. There are
already several docs in the docs/design/ sub-directory which use
asciidoc (and some more in branches that will be merged).

However, I agree it is good to be consistent and use a single tool where
possible. But currently the Doxygen design documentation seems in bad
shape. We should first clean it up and make it straightforward to add
new content. Using Doxygen is outside the scope of our initial
decisions to use asciidoc for this ticket which has already been
implemented, so let's create further tickets for this. The main goal of
this ticket was to get the documentation in the repo so it can be
maintained.

I don't think we necessarily need to use the same tool. After all, these are two similar but different tasks. User documentation needs something else than developer documentation.

With developer documentation, the formatting quality and such can be significantly lower. It doesn't have to impress. It is enough to be just readable. On the other hand, the developer documentation must be easily and fast editable, which docbook is far away from that. So it makes sense to me to use different tools for different kinds of documentation.

comment:8 in reply to: ↑ 7 Changed 7 years ago by jreed

Replying to vorner:

I don't think we necessarily need to use the same tool. After all, these are two similar but different tasks. User documentation needs something else than developer documentation.

With developer documentation, the formatting quality and such can be significantly lower. It doesn't have to impress. It is enough to be just readable. On the other hand, the developer documentation must be easily and fast editable, which docbook is far away from that. So it makes sense to me to use different tools for different kinds of documentation.

There is a misunderstanding here. My comment was not about docbook and not about user documentation.

comment:9 in reply to: ↑ 7 ; follow-up: Changed 7 years ago by muks

  • Owner changed from muks to vorner

Hi Michal

Replying to vorner:

Hmm. I think either one of these changes would suffice, but both is
unexpected. I mean, if I want to compile the software, I usually don't
require the development documentation, so it being skipped is OK and
what I want. But if I actually ask to generate the development
documentation explicitly, by make devel, then it should probably
fail if it can't be fulfilled, not create dummy files.

As discussed on Jabber, we pick this behavior:

  • make devel creates the documentation. It is not created during default makes.
  • If during make devel the tools are not found, it is a make error and there is no recovery.

Also, it looks awkward to put text into a png image (and they don't
show at all in the document, if asciidoc is installed and the plantuml
isn't). What about placing a dummy png file there (containing the text
as image) and copy it to the target one instead of echoing a text
there?

As above, the rules have been modified so that the devel target breaks
the build if tools are not installed. So this case should no longer be a
problem.

Is this generic make syntax, or GNU extension?

BUILT_SOURCES = \
	$(UML_FILES:.txt=.png) \
	$(TEXT_FILES:.txt=.html)

I am not sure. Maybe we should put this branch through the builders and
see what happens.

That could work. I also think using `$(patsubst
$(UML_FILES),%.txt,%.png)` should work (I believe that one is
standard), I don't know about this.

This failed for me with the following error:

make: *** No rule to make target `%.png', needed by `devel'.  Stop.

However a modified syntax worked, so I have committed that.

Are the diagram sources written by hand, or some tool helps with them?
Writing the formatted text is easy, but these seem rather more
complex.

They have been written by hand.

They are rather simple actually. It looks complicated because there are
so many instructions. But they are rather a set of sequential
instructions, just bulky. Personally, I prefer that we code it up
manually (so that the text is as readable as it can be) and not using a
visual tool, but I guess both ways is fine as long as it's maintainable.

I don't know. I did write some postscript images for my thesis. But I find it easier to draw them often.

Jinmei must have used something to make his, maybe we could just use that? And import his images as they are?

I think someone mentioned that Jinmei uses something MacOS specific, and
probably even closed source. So we can't rely on that tool for a shared
repo.

comment:10 in reply to: ↑ 9 Changed 7 years ago by vorner

  • Owner changed from vorner to muks
  • Total Hours changed from 0 to 2.42

Hello

Replying to muks:

Jinmei must have used something to make his, maybe we could just use that? And import his images as they are?

I think someone mentioned that Jinmei uses something MacOS specific, and
probably even closed source. So we can't rely on that tool for a shared
repo.

OK, that's fair. I still think it would be more comfortable to draw diagrams than to write them. But that's probably out of scope of the ticket. I'm going to bring it up on the ML.

I think this can be merged now.

comment:11 Changed 7 years ago by muks

  • Resolution set to fixed
  • Status changed from reviewing to closed

Merged to master branch in commit c4004066611a83ea5589af57bf07172da5a4aa94:

* fcbb1a9 [3006] Use a more portable makefile pattern substitution syntax
* f1c3990 [3006] Fail make if tools are not found during "make devel"
* b99e16a [3006] Use the devel target just like in upper level directories
* 7a55d68 [3006] Generate dummy targets when tools are not available
* df2c166 [3006] Fix error messages that are printed
* 38ff623 [3006] Update argument syntax
* f3599de [3006] Add the last sequence diagram
* 51861a1 [3006] Remove excess space
* 0507bba [3006] Add intitial version of another sequence diagram
* 7e343de [3006] Add alt text for image
* 46544d4 [3006] Add another sequence diagram
* bdf66e1 [3006] Add note that the class diagram has to be improved
* d6b484d [3006] Add temporary overview class diagram
* 8cb8350 [3006] Fix various bits in auth module using mapped memory segment section
* 472b197 [3006] Add alt text for image
* 8c4f48f [3006] Add .gitignore
* bd4a777 [3006] Add to build system
* 5485e72 [3006] Add auth-mapped PlantUML diagram
* df956ae [3006] Convert Jinmei's data source classes documentation to asciidoc

Resolving as fixed. Thank you for the reviews Michal.

Note: See TracTickets for help on using tickets.