diff --git a/LICENSE b/LICENSE index f3adc74..a52160a 100644 --- a/LICENSE +++ b/LICENSE @@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + diff --git a/Makefile b/Makefile index 5cd9f2b..a6e09c1 100644 --- a/Makefile +++ b/Makefile @@ -11,14 +11,13 @@ BIB_TXT_FILES := $(sort $(wildcard bibs/*.txt)) all: project_html ## create html -#html: $(HTML_FILES) -html: project_html +html: $(HTML_FILES) + $(PRINT) "make $@ done." _site/%.html: %.qmd _quarto.yml bibs/mybib.bib quarto render $< --to html --no-clean --quiet $(PRINT) "make $@ done." - project_html: $(QMD_FILES) _quarto.yml bibs/mybib.bib quarto render --to html $(PRINT) "make $@ done." @@ -48,14 +47,14 @@ publish: html ## clean up -JUNK = *.log +JUNK = *.log index_files jupyter_files clean: - rm -f $(JUNK) + rm -rf $(JUNK) $(PRINT) "make $@ done." ## clean up everything including the output -OUTS = _site _freeze jupyter_files bibs/mybib.bib +OUTS = _site _freeze bibs/mybib.bib realclean: clean rm -rf $(OUTS) diff --git a/README.md b/README.md index 7bdc87a..1cdef7b 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,14 @@ quarto-example [![pages build & deploy](https://github.com/rreece/quarto-example/actions/workflows/pages.yml/badge.svg)](https://github.com/rreece/quarto-example/actions/workflows/pages.yml) -Easy way to compile markdown into documents. +Easy way to compile markdown into scholarly documents, html or pdf This project is meant to make writing easier and more productive. + +What this is for +---------------------------------- + So you want to write a document. Maybe you'll share it on the web. Maybe you want a polished pdf. @@ -15,12 +19,24 @@ Maybe it's a blog, research paper, book draft, or just a set of notes. You don't want to think about typesetting details. You just want to throw your ideas in some plain text files and call `make`. -This is my first example of using [quarto](https://quarto.org/), +This is a starter template for using [quarto](https://quarto.org/), following the quarto [Get Started](https://quarto.org/docs/get-started/hello/text-editor.html). +It seems to achieve a lot of what I was trying to do with my +similar projects, +[markdown-memo](https://github.com/rreece/markdown-memo) and +[markdown-easy](https://github.com/rreece/markdown-easy): +*make technical and scholarly writing easier and more productive*. -You can see the rendered website here: -[rreece.github.io/quarto-example](https://rreece.github.io/quarto-example/) +This package makes it very easy to compile text taken in +[Markdown](https://daringfireball.net/projects/markdown/) +to valid xhtml or to a pdf via LaTeX. +It can be used to make static websites quickly, +for example (this site): + + +This same document compiled to a pdf can be found here: + Quick start @@ -30,28 +46,63 @@ Quick start TODO +``` +TODO +``` + ### Setting up a new document TODO +``` +TODO +``` + ### Compile to html -Just call `make` +Just call + +``` +make +``` ### Compile to pdf -Just call `make pdf` +Just call + +``` +make pdf +``` TODOs ---------------------------------- +Documentation: + +- [ ] Finish Quick start in this README + +Build: + +- [ ] GitHub Actions for testing for build artifacts before deployment +- [ ] Change GitHub Actions to use this Makefile +- [ ] Conditionally build different parts of the document +- [ ] Make bibliography optional +- [ ] Makefile target for starting a new document +- [ ] Make it easy to create a small single page doc + +Rendering issues: + - [ ] [Issue](https://github.com/quarto-dev/quarto-cli/issues/2275) with labeling equation in `align` for pdf + +Style: + - [x] Add `_quarto.yaml` settings for custom css - [ ] Add `_quarto.yaml` settings for latex styling +- [ ] Polish book pdf output Note these quarto issues diff --git a/_quarto.yml b/_quarto.yml index d704534..79b9cca 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -15,6 +15,7 @@ book: - math.qmd - figs-tables.qmd - jupyter.qmd + - conclusion.qmd - references.qmd appendices: - actions.qmd diff --git a/bibliographies.qmd b/bibliographies.qmd index 681e68c..4fee070 100644 --- a/bibliographies.qmd +++ b/bibliographies.qmd @@ -32,15 +32,18 @@ Plato below. For example, the `mybib.txt` file in this document is - ATLAS Collaboration. (2008). The ATLAS Experiment at the CERN Large Hadron Collider. *Journal of Instrumentation*, 3, 08003. https://cds.cern.ch/record/1129811 - ATLAS Collaboration. (2012). Observation of a new particle in the search for the Standard Model Higgs boson with the ATLAS detector at the LHC. *Physics Letters B*, 716, 1--29. https://arxiv.org/abs/1207.7214 - Feynman, R.P. (1963). *The Feynman Lectures on Physics, Volume I*. California Institute of Technology. http://www.feynmanlectures.caltech.edu/I_03.html - Feynman, R.P. (1965). The Development of the Space-Time View of Quantum Electrodynamics. Nobel Lecture, December 11, 1965. http://www.nobelprize.org/nobel_prizes/physics/laureates/1965/feynman-lecture.html - Guest, D., Collado, J., Baldi, P., Hsu, S. C., Urban, G., & Whiteson, D. (2016). Jet flavor classification in high-energy physics with deep neural networks. *Physical Review D*, 94, 112002. https://arxiv.org/abs/1607.08633 - Miller, A. (2014). Realism. *Stanford Encyclopedia of Philosophy*. http://plato.stanford.edu/entries/realism/ - Plato. (2000). *The Republic*. (G. Ferrari, Ed. & T. Griffith, Trans.). Cambridge University Press. [(Originally written ca. 380 BCE)] - Quine, W.V.O. (1969). Natural kinds. In *Ontological Relativity and Other Essays* (pp. 114--138). Columbia University Press. - van Fraassen, B. (1980). *The Scientific Image*. Oxford University Press. +``` +ATLAS Collaboration. (2008). The ATLAS Experiment at the CERN Large Hadron Collider. *Journal of Instrumentation*, 3, 08003. https://cds.cern.ch/record/1129811 +ATLAS Collaboration. (2012). Observation of a new particle in the search for the Standard Model Higgs boson with the ATLAS detector at the LHC. *Physics Letters B*, 716, 1--29. https://arxiv.org/abs/1207.7214 +Feynman, R.P. (1963). *The Feynman Lectures on Physics, Volume I*. California Institute of Technology. http://www.feynmanlectures.caltech.edu/I_03.html +Feynman, R.P. (1965). The Development of the Space-Time View of Quantum Electrodynamics. Nobel Lecture, December 11, 1965. http://www.nobelprize.org/nobel_prizes/physics/laureates/1965/feynman-lecture.html +Guest, D., Collado, J., Baldi, P., Hsu, S. C., Urban, G., & Whiteson, D. (2016). Jet flavor classification in high-energy physics with deep neural networks. *Physical Review D*, 94, 112002. https://arxiv.org/abs/1607.08633 +Miller, A. (2014). Realism. *Stanford Encyclopedia of Philosophy*. http://plato.stanford.edu/entries/realism/ +Plato. (2000). *The Republic*. (G. Ferrari, Ed. & T. Griffith, Trans.). Cambridge University Press. [(Originally written ca. 380 BCE)] +Quine, W.V.O. (1960). Carnap and logical truth. *Synthese*, 12, 350--374. +Quine, W.V.O. (1969). Natural kinds. In *Ontological Relativity and Other Essays* (pp. 114--138). Columbia University Press. +van Fraassen, B. (1980). *The Scientific Image*. Oxford University Press. +``` If you do not want to use simplified txt files to generate bibtex, and you want to write your own bibtex, diff --git a/conclusion.qmd b/conclusion.qmd new file mode 100644 index 0000000..8711886 --- /dev/null +++ b/conclusion.qmd @@ -0,0 +1,14 @@ +--- +title: "Conclusion" +date: today +--- + +This project is meant to make writing easier and more productive. + +[quarto-example](https://github.com/rreece/quarto-example) +is developed by [Ryan Reece](http://rreece.github.io/). + +Let me know what you think at [github.com/rreece/quarto-example](https://github.com/rreece/quarto-example) +or Twitter [@RyanDavidReece](https://twitter.com/RyanDavidReece). + + diff --git a/figs-tables.qmd b/figs-tables.qmd index a6435f4..8ff61fb 100644 --- a/figs-tables.qmd +++ b/figs-tables.qmd @@ -17,14 +17,12 @@ For example, of science. CC BY-SA 3.0 (2013) [Wikimedia Commons](https://en.wikipedia.org/wiki/Science#/media/File:The_Scientific_Universe.png). ](img/1024px-the-scientific-universe.png){#fig-scientific-universe} -produces: +produces @fig-scientific-universe. ![The scale of the universe mapped to the branches of science and the hierarchy of science. CC BY-SA 3.0 (2013) [Wikimedia Commons](https://en.wikipedia.org/wiki/Science#/media/File:The_Scientific_Universe.png). ](img/1024px-the-scientific-universe.png){#fig-scientific-universe} -[@Fig-scientific-universe] shows some cool things. - Lorem ipsum dolor sit amet, duo ut putant verear, nam ut brute utroque. Officiis qualisque conceptam te duo, eu vim soluta numquam, has ut aliquip accusamus. Probo aliquam pri id. Mutat singulis ad vis, eam euismod pertinax @@ -44,24 +42,30 @@ Another example: SM Higgs boson signal at that mass with its $\pm{}1\sigma$ band. The horizontal dashed lines indicate the $p$-values corresponding to significances of 1 to 6$\sigma$\ [@ATLAS_2012_Observation_of_a_new_particle_in_the_search]\. - ](img/ATLAS-local-p0-vs-mH.png){#fig-ATLAS-local-p0-vs-mH} + ](img/ATLAS-local-p0-vs-mH){#fig-ATLAS-local-p0-vs-mH} -produces: +produces @fig-ATLAS-local-p0-vs-mH. ![The observed (solid) local $p_{0}$ as a function of $m_{H}$ in the low mass range. The dashed curve shows the expected local $p_{0}$ under the hypothesis of a SM Higgs boson signal at that mass with its $\pm{}1\sigma$ band. The horizontal dashed lines indicate the $p$-values corresponding to significances of 1 to 6$\sigma$\ [@ATLAS_2012_Observation_of_a_new_particle_in_the_search]\. - ](img/ATLAS-local-p0-vs-mH.png){#fig-ATLAS-local-p0-vs-mH} + ](img/ATLAS-local-p0-vs-mH){#fig-ATLAS-local-p0-vs-mH} + +Note that by leaving the file suffix implied, `img/ATLAS-local-p0-vs-mH`, +quarto will automatically pick the available png or jpg when producing html output, +but will prefer an available pdf figure when producing pdf. [^PdfAllowsVectorGraphics] +[^PdfAllowsVectorGraphics]: This allows us to include vector graphics images in pdf format when + producing pdf output, whereas when producing html, we use rasterized formats: jpg or pdf. You can refer to labeled figures like this: - [@fig-ATLAS-local-p0-vs-mH] shows the $p_{0}$ value as a function of the reconstructed + @fig-ATLAS-local-p0-vs-mH shows the $p_{0}$ value as a function of the reconstructed Higgs mass from the ATLAS experiment. -[@fig-ATLAS-local-p0-vs-mH] shows the $p_{0}$ value as a function of the reconstructed +@fig-ATLAS-local-p0-vs-mH shows the $p_{0}$ value as a function of the reconstructed Higgs mass from the ATLAS experiment. diff --git a/img/1024px-the_scientific_universe.png b/img/1024px-the_scientific_universe.png deleted file mode 100644 index d7d5b4d..0000000 Binary files a/img/1024px-the_scientific_universe.png and /dev/null differ diff --git a/index.qmd b/index.qmd index b1f74b3..e73325d 100644 --- a/index.qmd +++ b/index.qmd @@ -1,8 +1,9 @@ ## Preface {.unnumbered} -I've always been looking for the tool that would help -technical and scholarly writing flow in a Markdown-driven way. +I've always been looking for the right tool that would help +technical and scholarly writing flow in a +[Markdown](https://daringfireball.net/projects/markdown/)-driven way. Managing figures, tables, equations, and bibliographies. Generating html, latex, or pdf. @@ -13,6 +14,6 @@ which I was trying to update and trim down into Then I discovered the [quarto](https://quarto.org) project that is very similar in spirit and has already -accomplished what I was trying to get to. +accomplished a lot of what I was trying to do. And they have a growing community. diff --git a/intro.qmd b/intro.qmd index 4cd76d5..b9a4ce8 100644 --- a/intro.qmd +++ b/intro.qmd @@ -9,12 +9,6 @@ number-sections: false What this is for -------------------------------------------- -This is a starter template for using [quarto](https://quarto.org/). -It seems to achieve a lot of what I was trying to do with -[markdown-memo](https://github.com/rreece/markdown-memo) and -[markdown-easy](https://github.com/rreece/markdown-easy): -*make technical and scholarly writing easier and more productive*. - So you want to write a document. Maybe you'll share it on the web. Maybe you want a polished pdf. @@ -22,10 +16,19 @@ Maybe it's a blog, research paper, book draft, or just a set of notes. You don't want to think about typesetting details. You just want to throw your ideas in some plain text files and call `make`. +This is a starter template for using [quarto](https://quarto.org/), +following the quarto +[Get Started](https://quarto.org/docs/get-started/hello/text-editor.html). +It seems to achieve a lot of what I was trying to do with my +similar projects, +[markdown-memo](https://github.com/rreece/markdown-memo) and +[markdown-easy](https://github.com/rreece/markdown-easy): +*make technical and scholarly writing easier and more productive*. + This package makes it very easy to compile text taken in [Markdown](https://daringfireball.net/projects/markdown/) to valid xhtml or to a pdf via LaTeX. -It can be used to make simple webpages quickly, +It can be used to make static webpages quickly, for example (this site): diff --git a/jupyter.qmd b/jupyter.qmd index fafb108..f659103 100644 --- a/jupyter.qmd +++ b/jupyter.qmd @@ -27,3 +27,8 @@ ax.set_rticks([0.5, 1, 1.5, 2]) ax.grid(True) plt.show() ``` + +This is executable code above, actually executed to generate @fig-polar +on the fly when building the document! + + diff --git a/templates/mystyle.css b/templates/mystyle.css index 9886260..106759c 100644 --- a/templates/mystyle.css +++ b/templates/mystyle.css @@ -23,3 +23,10 @@ code { } +/* references ------------------------------------------------------- */ + +div#refs +{ + font-size: 0.9em; +} +