search

ossf / secure-sw-dev-fundamentals

Secure Software Development Fundamentals courses (from the OpenSSF Best Practices WG)
Creative Commons Attribution 4.0 International
175 stars 47 forks source link

Generate a PDF for a book #115

Open david-a-wheeler opened 1 year ago

david-a-wheeler commented 1 year ago

Consider making tweaks so we can generate a PDF to be printed as a book.

This material was developed to be used online, but some people may prefer to learn from it as a book. For the most part this could be easily done by converting the markdown to PDF, e.g., by using pandoc.

There might be a few minor things to tweak for that to work, but the big problem I know of is the many quiz questions. Currently they are in edX format, which isn't part of markdown. We could change for the format of the questions in the original to be in markdown (possibly with HTML comment tags), or do post-processing and leave the original as-is.

Would it be better to change the quiz format to something else? Or what? Comments welcome.

merlos commented 1 year ago

Hi,

I think it is good for the learning to have tests that challenge the understanding of the chapter/section and quiz.

I see two scenarios in which the PDF could be used:

1) Hardcopy. In that case, I prefer to have the answers at the end of the book. 2) PDF reader. In this case, going to the end of the file and come back to the chapter I am reading is cumbersome. In this scenario I prefer to have the answers close to the context, but in a way I cannot see the answers right away. So maybe within the next page.

In both cases, it may require some post-processing.

Thanks for the course. Best, Juan.

david-a-wheeler commented 1 year ago

I hate to have 2 different "kinds" of PDF; I think the hardcopy should be a printout of the PDF. So I think we should pick some format & be done. Thankfully, in a PDF reader we can have hyperlinks, so the hyperlinks can go anywhere. Either "soon after" or "end of material" would work I think.

merlos commented 1 year ago

Maybe I was not clear... I was not suggesting to implement both but rather to expose two options, one for each different use cases. I would hate to have to maintain two different "kinds" of PDF, too. Best.

PS: One thing, with pandoc, last time I used it to convert a MD to PDF I noticed the links by default had the same look and feel as normal text, and only through hover could be differentiated... but it may be my setup...