From 1c3e718e6415153975b7586db3fc39da0b3c17e0 Mon Sep 17 00:00:00 2001 From: Ryan Reece Date: Thu, 26 Oct 2023 21:01:28 -0700 Subject: [PATCH] fix readme --- README.md | 249 ++---------------------------------------------------- 1 file changed, 5 insertions(+), 244 deletions(-) diff --git a/README.md b/README.md index c7ca033..9ed630d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ -markdown-memo +markdown-easy =========================== -[![CI badge](https://github.com/rreece/markdown-memo/actions/workflows/ci.yml/badge.svg)](https://github.com/rreece/markdown-memo/actions) +[![CI badge](https://github.com/rreece/markdown-easy/actions/workflows/ci.yml/badge.svg)](https://github.com/rreece/markdown-easy/actions) + +Easy way to compile markdown into documents. *NOTE: I have a new motivation to clean up this project. Please let me know if you find it useful.* @@ -15,245 +17,10 @@ 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 package makes it very easy to compile text taken in -[Markdown](http://daringfireball.net/projects/markdown/) -to valid xhtml or to a pdf via LaTeX. -It can be used to make simple webpages quickly, -for example: - - -This same document compiled to a pdf can be found here: - - - -Requirements ----------------------------------- - -- make -- LaTeX (texlive/mactex) -- python >= 3.8 -- pandoc >= 2.13 -- [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) -- matplotlib (for pagecount and wordcount plots) -- xpdf (pdfinfo command for pagecount) - -On my Mac, I used to install the missing dependencies through -[macports](https://www.macports.org/), -but beginning with OS 10.11, I started using -[homebrew](http://brew.sh/). - -First, if you are on a Mac, you should install -[Xcode](https://developer.apple.com/xcode/) -through the Apple app store to get `make` and basic build utilities. - -Some basic requirements I had to install with *homebrew* -were the following, and I got [pip](https://pip.readthedocs.io/en/stable/installing/) -and used it to install somethings: - - brew install wget - brew install xpdf - sudo python get-pip.py - sudo pip install scipy - sudo pip install matplotlib - sudo pip install pandas - -Then, with *homebrew*, the main packages to install are - - brew cask install mactex - brew install pandoc - brew install pandoc-citeproc - brew install pandoc-crossref - -Instead of homebrew, some years ago, with *macports* I installed - - sudo port selfupdate - sudo port install texlive-latex texlive-latex-recommended texlive-latex-extra texlive-math-extra - sudo port install pandoc - sudo port install hs-cabal-install - cabal update - cabal install pandoc-citeproc pandoc-crossref - -If something doesn't work for you, please let me know! -I'll do my best improve the documentation and make -the software more robust as time allows. - -TODO: Rewrite install instructions for Ubuntu and Mac. -I'm sorry. - - -Features ----------------------------------- - -### html - -- [disqus comments](disqus.com) -- mathjax LaTeX rendering -- google analytics tracking -- automatically generates an `index.md` - -If you want to write your own `index.md`, -then put the same markdown in `index.txt`. - -### pdf - -- LaTeX -- fancyheader - -### both - -- appendices -- bibtex bibliographies -- footnotes -- multiple authors -- word- and page-count plots (see below) - - -Getting started ----------------------------------- - -- Clone/fork this package and possibly rename the `markdown-memo` - directory as your project. -- Put some `*.md` files in that directory. -- In those files, just start writing the `h1` heading. - There's no need for additional markup or html. - Examples of [Markdown](http://daringfireball.net/projects/markdown/) - syntax are - - Section 1 - ================================= - - Sub-section 1 - --------------------------------- - - [Lorem ipsum](https://en.wikipedia.org/wiki/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 - an, ea tale volumus vel. At porro soleat est. Debet facilis admodum an sed, - at falli feugiat est. - - 1. one - 1. two - 1. three - - You can do latex in-line, $e^{i\pi} + 1 = 0$, like that. - Or equations: - - \begin{equation} - \int_{\partial\Omega} \omega = \int_{\Omega} \mathrm{d}\omega \,. - \end{equation} -- Edit the metadata in `meta.yaml`. -- Call `make` to generate valid xhtml. -- Call `make pdf` to generate a pdf document. -- Call `make clean` to delete temporary LaTeX files. -- Call `make realclean` to additionally delete the output html and pdf files. - -I use an image of my email to hide it from text crawlers. -Please replace `img/my-email.png` with a screenshot of your -email address instead of mine, -or just remove the use of the image in `meta.yaml`. - -Customize the files in `templates/` to adjust the format -of the output html and pdfs files to your needs. - -If you want to put the html online, perhaps a solution for you, -because it's free and easy, would be to host the pages at github. -See: [pages.github.com](https://pages.github.com/). - - -Special files ----------------------------------- - -There are a few special files that help steer the execution of markdown-memo -or are otherwise exceptional. - -Documentation: - -- `README.md` - This file. Please empty this file and adapt it to your project. - -Primary files edited by the user: - -- `meta.yaml` - The main metadata file controlling the project in many ways. -- `*.md` - Any other user-created Markdown files, the markup of your document. - -Optional files: - -- `index.[md,txt]` - The top-level, root file of your project. By default, if `index.txt` is missing, - a table of contents is generated for `index.md`, otherwise (the user-written) `index.txt` - is copied to be the `index.md`. -- `bib_index.md` - Call `make bib_index.md` to generate this file. It is to help incoorporate citations - into your document by being an automatically generated list of the references, with footnotes, - created from the available bibliography files in `bibs/`. -- `order.txt` - Optionally, the user can create this file, which should have a list of - Markdown files used in the document, one-per-line, in the order as to be used for the - navigation buttons in the html template. By default, building the html will generate this - file if it doesn't already exist, with the Markdown files listed in alphabetical order. - If one names the Markdown files something like `01-first-section.md`, `02-second-section.md`, etc., - then the order should be handled automatically. - - -Disqus integration ----------------------------------- - -You can choose to append a comments section at the end of your html. -Just register a user name and the site name with [disqus.com](disqus.com). -Then in the `meta.yaml`, set `disqus: true`, and set your `disqus_shortname`. - - -More info ----------------------------------- - -The documentation in this README is expanded on in the markdown-memo example: -[rreece.github.io/sw/markdown-memo](http://rreece.github.io/sw/markdown-memo) - - -Word count ----------------------------------- - -Note that word-count and page-count plots are generated when you call `make pdf`. -You might want to keep these around in the `README.md` for your document. - -![Page count over time.](wordcount/pages.png) - -![Word count over time.](wordcount/words.png) - - -Wish list / TODOs ----------------------------------- - -- ~~Automatically generate an index.md with a TOC.~~ -- ~~Find and replace the default figure environment to be `\begin{figure}[tph]` instead of `\begin{figure}[htbp]`.~~ -- ~~Add conditionals to the `Makefile` such that `templates/refs.md` is only added for documents that have references.~~ -- ~~Write a script to generate a md file with footnotes and citations defined given a bibliography (`make_bib_index.py`).~~ -- ~~Find and replace such that LaTeX figures use pdf figures while html uses raster png/jpg.~~ -- ~~Optionally make a TOC automatically in the html.~~ -- ~~Make links to previous and next sections (if they exist) in the navigation box in the html.~~ -- ~~Finish the basic documentation in the markdown-memo example document.~~ -- ~~Make a template that works with [REVTeX](https://journals.aps.org/revtex).~~ -- ~~Make a template that works with [JHEP](https://jhep.sissa.it/jhep/help/JHEP_TeXclass.jsp).~~ -- ~~Hack equation references to be done the same as figure and table references. `[@eq:stokes]` → `eq.\ $\eqref{eq:stokes}$`~~ -- ~~PlotTable float~~ -- Allow tables to be given as csv files. -- Fix TOC spacing issues with REVTeX. -- Fix Author issues with JHEP. -- Make the use of tmp files more robust. -- Test and explain the installation and requirements better on different systems. -- Fix TOC issues when calling `make ohtml`. -- Explain `make html` vs `make ohtml` in the documentation. -- Get tables to be normal `\begin{table}[bph]` instead of the `longtable` environment. -- References to labels on other pages unfortunately don't work in html. -- ~~Add some basic CI.~~ -- Rewrite install instructions above. -- Fix `install_for_mac`. -- Make better dark template. -- Clean up the yaml conventions. -- Rewrite a more simple and clean version of the whole thing. - See also ---------------------------------- -- [rreece.github.io/sw](http://rreece.github.io/sw/) - [rreece.github.io/sw/markdown-memo](http://rreece.github.io/sw/markdown-memo) - [kprussing.github.io/writing-with-markdown](http://kprussing.github.io/writing-with-markdown/) - [pandoc.org/README.html](http://pandoc.org/README.html) @@ -272,11 +39,5 @@ Author ---------------------------------- Ryan Reece ([@rreece](https://github.com/rreece)) -Created: July 29, 2014 - - -License ----------------------------------- +Created: October 26, 2023 -Copyleft 2014-2023 Ryan Reece -GPL-3 [LICENSE](LICENSE)