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
