Should `gen/` files always be a reference for `doc/` or is the manual output rather put under `res/`?

[timmwille]

[timmwille]

in reference to the thought in #6

[hoijui]

I try to rephrase the question in a way I can understand it, and so that it means the same that @timmwille wanted to say - or at least as I understood him in our call yesterday:

Should

1. all generated files always go to gen/,
2. or, should manually generated[*] ones rather go to res/ instead?

Keep in mind that we might want to link to all generated files
from within doc/ and other places.

[*] e.g. a technical drawing exported from FreeCAD through the GUI

[hoijui]

the answer is:

1. all generated files always go to gen/, whether fully automated or partially manually generated.

reasons:

1. This way, gen/ could be a git sub-module, which allows to "delete" it's history form time to time - without loosing integrity in past commits - by simply linking to a fresh repo URL.
2. It clarifies that a file is generated, and should not be manually edited directly, but only potentially re-generated.
3. If it is e.g. linked to from the doc, but not present, one could easily assume that it is missing because it still needs to be generated, and thus could start to figure out how to do this, which is likely through a script in run/, or from a file in the src/ dir. (eg. if the missing file is gen/src/anim/XXX/out.mov, we would look under src/anim/XXX/ for a way to generate it.)
4. On the other hand, it allows one to assume that all files under res/ can be manually edited, if a change there is required

[timmwille]

@hoijui thank you with you explanation I like the approach.

Keep in mind in some cases one can only (re)generate manually when the software is the same version or additional plugins and curtain steps are followed → so technically that is a must have in the documentation in order to be fully independent when the gen/ directory gets removed/regenerated completely via version.

What would really help: something that tracks manually generated files per release, so it is easy to have a checklist what needs manual replacement for the next release !! (is that even possible?) 😄

[hoijui]

something that tracks manually ... *brain 'splodes*
manua... ah I got it! it is the hand (from latin "mano" .. or something like that), right?

... or in other words: please x-plain!

when preparing a release, delete all manually generated files (using a list of these files that is created manually once), and then manually generate one after the other, until al are there again?
you know you re-generated all of them, because git will then only show changed files, instead of deleted ones.
would that work?
needs no tool then.

[timmwille]

Hmm I would probably need to test, interesting Idea to use git as a (non)indicator of changed files for that. So if a file is not popping up it was not generated again, that holds some magic remembering aspects to it, because directories could also be empty or simply no update there. So when the source file was changed but no respective output was generated and for that path/tool/file also no automatic generating script is in place it would be nice to have an indicator that does the following:

"Hey you got a change in source file XYZ and there is no autogenerating script in place for your release, but the corresponding file xyz in the gen/ directory has not changed since the last release, you might want to check it out/update manually!"

An yes many zip/binary kind of source files will also change when there was just the view changed, but not actually anything in the design files. So it will be an optional checker, that just notifies but is not mandatory to update the output files.

I'm really not so sure if Git will be a solution here alone. → As there are "License Checkers" "Active URL Checker" "Security Risk Checkers" and more, it might be a good idea to add a "Generated Output Checker" or so...?