Documentation image source
chrisj at rtems.org
Thu Oct 8 03:29:03 UTC 2020
On 8/10/20 2:23 pm, Joel Sherrill wrote:
> On Wed, Oct 7, 2020, 8:12 PM Chris Johns <chrisj at rtems.org
> <mailto:chrisj at rtems.org>> wrote:
> On 8/10/20 12:04 pm, Joel Sherrill wrote:
> > On Wed, Oct 7, 2020, 8:01 PM Chris Johns <chrisj at rtems.org
> <mailto:chrisj at rtems.org>
> > <mailto:chrisj at rtems.org <mailto:chrisj at rtems.org>>> wrote:
> > Hi,
> > In an update of my rtems-docs.git repo I noticed some new image source
> > $ find . -name \*.dot
> > ./images/eng/bld-bsp.dot
> > ./images/eng/bld-deps2.dot
> > ./images/eng/bld-bsp2.dot
> > ./images/eng/bld-deps.dot
> > Do we have a policy on what image source types can be used? Any
> additional image
> > source needs to support FreeBSD and Linux.
> > Images can be difficult to get right so I understand there is a need for
> > flexibility and tolerance but I think we need to consider how we
> manage the
> > process and quality so we maintained high quality documentation. For
> example on
> > my desktop I cannot read the HTML `bld-deps.png` and clicking on it
> loads a
> > small image which is clearer but small. The page is ...
> > The PDF view looks OK.
> > I can see we have as image source the following extensions:
> > .puml
> > .ditaa
> > .svg
> > .dot
> > .odg
> > Some formats are old and imported so we live with those but maybe we need
> > tickets to have them move to something that is simpler to maintain.
> > I see generated .png and .pdf for some images which I am questioning
> we need.
> > The user document images I have contributed are only .png files so I
> am not sure
> > why a PDF is needed for some.
> > How are the .dot image sources converted to the required output
> format(s)? I
> > cannot see any information on what to do, what packages I need to
> install and
> > the options I need. For the puml and ditaa source I contributed I
> added waf
> > support, tested on Linux and FreeBSD and update the top level doco.
> > Graphviz.
> Thanks but I was hoping for something a little more specific, like a `pkg
> install ...` command and a command line to run. I think it is important when
> wanting to maintaining quality. :)
> That is the name of the package. May vary with upper or lower case. CentOS RPM
> is graphviz.
I am sure it is something like that on FreeBSD. I have not looked.
> Are there any figures we do not appear to have source for? Or they aren't in an
> open format? I thought we had killed all those in our last Google Code In.
Good question, I think there are some I did a long time ago that might need to
be redone. The svg ones. I have not checked.
> > If you can build Doxygen with graphics, you should have dot. We want dot
> for sure.
> Sure, happy to be dot source integrated and managed.
> I surprised one of my sons by using dot to show them the dependency graph for
> them to graduate on time. Coloured nodes based on semester offered and could
> visually identify longest sequence of courses and which had no prerequisites
> left for him.
That is such a nerd Dad solution! Well done, I love it :)
> PlantUML can draw more types of figures and they often look better but it can
> embed dot.
OK, I have not used dot so I do not know. The concern is not so much the tool
but the options used to make something work and be just right. We need to
capture what is used.
More information about the devel