Actually, Mathieu made a very good point. Asciidoc does indeed support
variables. I think that's the best middle solution.
On Mon, Sep 10, 2018 at 3:21 PM Mathieu Lirzin
<[email protected]> wrote:
>
> Hello,
>
> Gil Portenseigne <[email protected]> writes:
>
> > A tool for this purpose is in my opinion do not fit, we need
> > to commit ourselves to doc maintainment, when the code base is changed.
> > I do not see any good working automation around that, this has to be
> > done manually to ensure a good documenation.
>
> Even if people try to be thorough, it is very likely that they will
> eventually overlook that the documentation needs to be updated.
>
> While I sympathize with any effort of avoiding the over-tooling trap, I
> think it is *very* important to have consistency between the
> documentation and the actual code in use for example ensuring that the
> code examples provided in the documentation are still working. Given
> the complexity of OFBiz, it would be really harmful for newcomers if
> that was not the case. AIUI having a mismatch of images while not being
> as damaging as a code example mismatch is still something that is
> important to avoid. As a consequence I would be in favour of some
> tooling that helps in that regard.
>
> I personnally don't mind the “../../..” thing if the documentation build
> process fails when the providing file name is incorrect. However if the
> issue is about readability, maybe Asciidoc provides a way to define
> variables? If so, file name prefixes could be defined with a variable
> with a meaningful name that could then be reused when referring to an
> external file.
>
> --
> Mathieu Lirzin
> GPG: F2A3 8D7E EB2B 6640 5761 070D 0ADE E100 9460 4D37
