Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

include program code in markdown #156

Closed
behoppe opened this issue Sep 2, 2022 · 2 comments · Fixed by #148
Closed

include program code in markdown #156

behoppe opened this issue Sep 2, 2022 · 2 comments · Fixed by #148
Assignees
Labels
enhancement New feature or request

Comments

@behoppe
Copy link
Member

behoppe commented Sep 2, 2022

Issues
@ailiop mentioned it would be nice to have example programs residing in a place where we can include their code in the relevant articles instead of copying and pasting. I verified this is possible, as documented here.

Additional discussion
The solution uses Eleventy's include, which means that the example programs should live somewhere inside the /src/_includes folder of the website repo. I think that presents us with the main design decision -- how exactly to organize our code files in that location.

We might put all our examples into /src/_includes/code. Then we could use an example /src/_includes/code/dummy.c by adding the following within the markdown body of an article

```opening ticks probably specify cilkc
{% include "code/dummy.c" %}
```closing ticks

This would show up as pictured below (in a silly example).

@ailiop shall I set up a folder /src/_includes/code? Or are there other possible configurations we'd like to consider?

Screenshot 2022-09-02 at 16-26-24 Cilkscale — the OpenCilk scalability analysis tool

@behoppe behoppe added the enhancement New feature or request label Sep 2, 2022
@behoppe behoppe self-assigned this Sep 2, 2022
@behoppe behoppe linked a pull request Sep 15, 2022 that will close this issue
@ailiop
Copy link
Contributor

ailiop commented Sep 16, 2022

I think this is a fine initial setup, thank you @behoppe.

Some thoughts:

  • In some cases, such as nontrivial codes for tutorials or blog posts, it may be beneficial to use page-specific subdirectories with Makefiles etc, to make it easier to review/validate/update the page contents if necessary.
  • It could be handy if the include shortcode accepted optional arguments with start/end line numbers. For example, this could facilitate showing the code for some function() but not for a test rig in main(), etc.
  • Once we agree on a specific coding style, we can use an appropriate .clang-format config file to make sure our codes are formatted accordingly. Moreover, I wonder if we could have some GitHub CI action do that automatically for all C/C++ files in src/_includes/code/.

@behoppe
Copy link
Member Author

behoppe commented Sep 16, 2022

Thanks @ailiop. I think we can add subdirectories as we need them.

I consider this item done (with #148), with these two "cans" getting "kicked":

  • include is built into the template language, and it does not support line numbers. Perhaps it's possible to write a separate shortcode that can encapsulate anything (e.g., include) and crop it? I leave that to a separate project.
  • I am glad to hear about .clang-format and look forward to how we use it to roll out a standard. Why don't we leave that for another project as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants