role_diagram modified

[teuben]

after a "make clean-more" two files are modified. I suspect I should not check them in,but this could cause a commit storm of contributors

    modified:   role_diagram.pdf
    modified:   role_diagram.svg

[mbtaylor]

Yes, don't check them in. This is ivoatex business, I suppose the files are modified because the ImageMagick/ghostscript/librsvg/?? setup is different on your machine than on the one which generated these files from source in the first place. @msdemlei might possibly want to comment further.

[msdemlei]

Mark is right, but I'd still be curious about the diff of the SVG. The PDF contains all kinds of crap, so I'm not surprised that comes out differently. The SVG is generated by ivoatex code, so I wonder what could be different there.

Material for a crib sheet: "If this happens to you and you didn't want to change the role diagram, say git checkout role_diagram.pdf".

[tomdonaldson]

That is interesting. While it's not clear how often this will happen, we can certainly keep an eye out for those files showing up in PRs.

I like the notion of a crib sheet. Is there a good place now for document editors and maintainers to look for how to use ivoatex? For example, I haven't been able to find guidance on which make targets should be use for what cases. I've been able to figure out just enough to do what I need to do, but I haven't been confident I'm doing the intended thing.

[tomdonaldson]

Never mind. I just found the note (http://ivoa.net/documents/Notes/IVOATex/index.html).

[teuben]

I tried adding ivoatex: git submodule init git submodule update

-include ivoatex/Makefile

to a Makefile on the document level. But then the first target is not right, I tried adding

all: $(DOCNAME).pdf

to the first target in the ivoatex/Makefile

All of this was just an attempt to satisfy the bootstrapping problems for newcomers. The informaton is actually in https://github.com/ivoa-std/architecture

git experts will perhaps know to look at the .gitmodules file and realize they need to get the submodules. Still, I was just trying to satisfy the more ignorant/lazy ones, but it seems we would need a lot more safety in what we have. Not sure if it's worth the effort. Maybe there should be a reminder comment before the include ivoatex/Makefile that would not cause the havoc of a first target. Or better yet, move the ivoatex: target after the -include....

then it got messier. ConeSearch has a dummy ivoatex directory :-(

[tomdonaldson]

Yes, git submodules are very useful for a lot of things, but can end up being pretty confusing for the uninitiated (and others!). The Astropy project is moving away from their astropy-helpers submodule because they found alternatives that simplified the packaging quite a bit (https://github.com/astropy/astropy-APEs/blob/master/APE17.rst).

I initially liked the notion of helping with this complexity in the Makefile, but thinking about it more, I'm less enthusiastic. That functionality would need to be included in each Doc's Makefile, and that starts to feel like too much of a maintenance headache to balance out amount it's going to help beginners.

Prominently mentioning the need for the --recurse-submodules on the git clone might be the best return on investment here. It was interesting to me that GitHub Desktop did the recursive clone by default, which is helpful for beginners.

[msdemlei]

The new makefile actually pulls ivoatex as necessary (and the new ivoatex template creates them this way). So, I'd say Peter's concern is addressed.

[tomdonaldson]

The new makefile actually pulls ivoatex as necessary (and the new ivoatex template creates them this way). So, I'd say Peter's concern is addressed.

Closing this issue.