Hi, Thomas! First, thanks for all the Babel docs maintenance you're doing and for looking into this. And thanks to Ihor for the helpful pros and cons. I've looked into this a bit now, but I'm still learning the build process, so let me know if I'm getting anything wrong.
>> "Thomas S. Dye" <[email protected]> writes: >>>> I'm asking because I'm happy to learn how to edit Org files so they >>>> are more likely to build. >>> I see 11 languages added to org-babel-load-languages list in >>> publish.sh and numerous warnings in .build.yml for languages not on >>> the list: >>> Warning (emacs): org-export: No org-babel-execute function for >>> octave. Not updating exported results. >>> >>> IIRC, many of the ob-doc-* files expect the Worg server to generate >>> and display a graphic file. Would it help if I uploaded graphic >>> files and changed the ob-doc-* files to point to these graphics, >>> rather than expecting the server to generate them on its own? I doubt it would help with the build problems, for the following reasons: 1. From the recent build-failure logs, it seems the problem is at the upload step, not the export step, and involves permissions/secrets, not particular files. I don't understand what the problem is, though. 2. The warnings are just warnings. If an Org document has a src block for a language not loaded by Babel, export will trigger a "no org-babel-execute" warning, regardless of =:eval= settings, but it still gets exported. But as the warning says, any results will not get updated. As long as there are no broken links, so the existing results link to existing graphics files, that should not be a problem for the build. (It could lead to discrepancies between source and linked graphics, if people are not careful to evaluate src blocks when they make changes in them, but that's another matter.) 3. Most blocks will not be evaluated in any case, since the default setting is =:eval no-export=. The exceptions are the ob-doc-* files for ditaa, dot, elisp, and org, which have some explicit =:eval yes= flags. There's an issue with ob-doc-dot.org that we need to look into ("Babel evaluation exited with code 127"), but otherwise these files do not raise any warnings when exported. 4. Generally, the graphics files are already uploaded; for worg/org-contrib/babel/languages, the graphics are found in the =images= subdirectory of the =/babel/= and =/languages/ dirs respectively. (Mirroring the published Worg site, I don't see any graphics that are not also in my Git clone of Worg. I assume that means they were initially evaluated/generated locally by the authors and the graphics files committed/pushed to Worg, not generated on the fly from Worg docs on the server.) There *may* be graphics files that haven't been uploaded and src blocks that are *expected* to generate them, but don't, because they do not have =:eval yes= set. This shouldn't be a problem for the build as long as there are no broken links. But the content will be incomplete, so if you spot any, please do evaluate them and upload the graphics. It looks like the example file drift.org is one such case (on my todo list for later this week): https://orgmode.org/worg/org-contrib/babel/examples/drift.html > Ihor Radchenko <[email protected]> writes: > >> This should probably be a question to Christian. >> >> I thought about his in the past and noted the following: >> 1. Currently, we have to set up all the extra babel requirements >> on CI build to make things work. Sometimes, it is a bit >> tricky. >> On the other hand, it serves as an additional layer for >> detecting >> ob-*.el test failures (although WORG is definitely not the >> place to >> test these things properly) >> 2. Some babel languages are already configured on CI, so things are >> partially working. Whether those need to be removed is a >> question, if >> we decide to generate images and code output manually >> 3. From time to time, we need to re-configure CI (with new debian >> releases). Maintaining babel configuration is a bit of extra >> maintenance burden. >> 4. Adding images means a bit more work for people writing worg >> pages. All good points. To the extent there is a policy in place, it is that code evaluation on the server upon expert is not allowed, but local exceptions can be made for a few supported languages (https://orgmode.org/worg/worg-setup.html). As such, the continuous integration of src block results is limited. It's cool, and possibly useful, to have the option of dynamically updated graphics done in, say ditaa or R with with data from sh and elisp. I think we should keep existing cases as long as the maintenance burden is tolerable and any build problems can be resolved. As Ihor says, it's an additional test layer. We could even consider enabling a few additional languages if there's a clear use case for them. (Latex would be nice, but probably way too heavy.) The ability to generate graphics on the fly in the build also potentially means the repository itself could be kept smaller, at the cost of more processing. But again, I think we generally want the illustrations tracked by Git, and that a contributor's default approach should be to initially commit and upload them. Thomas S. Dye writes: > Christian, I'm happy to edit the ob-doc-*.org files to standardize. > If the CI approach is better, then I'm happy with that, too. Thanks for the offer, but I don't think we need to standardize. We can solve specific problems as we find them. WDYT? Regards, Christian
