BIND 10 #3006: Import datasource design documentation into BIND 10 git repo

[BIND 10 Development]

#3006: Import datasource design documentation into BIND 10 git repo
-------------------------------------+-------------------------------------
            Reporter:  muks          |                        Owner:
                Type:  task          |  vorner
            Priority:  medium        |                       Status:
           Component:                |  reviewing
  documentation                      |                    Milestone:
            Keywords:                |  Sprint-20130709
           Sensitive:  0             |                   Resolution:
         Sub-Project:  DNS           |                 CVSS Scoring:
Estimated Difficulty:  0             |              Defect Severity:  N/A
         Total Hours:  0             |  Feature Depending on Ticket:
                                     |          Add Hours to Ticket:  0
                                     |                    Internal?:  0
-------------------------------------+-------------------------------------
Changes (by muks):

 * owner:  muks => vorner


Comment:

 Hi Michal

 Replying to [comment:7 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 `make`s.

 * 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.

-- 
Ticket URL: <http://bind10.isc.org/ticket/3006#comment:9>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development