Document DiCy vs arara and latexmk #89
Conversation
|
@yudai-nkt Please take a look at this PR when you get a chance. Any feedback, no matter what the level of detail, is much appreciated. Please feel free to add line comments or anything else you think is appropriate. Thanks again! |
There was a problem hiding this comment.
Most of the comments are just personal preference or even due to my poor English comprehension, so feel free to ignore if you don't think you need to change.
Besides the line comments, I think it would be nice if some TL;DR (describing what kind of arara/latexmk's limitation Dicy has overcome) is added. IIUC, DiCy's advantages include
- it can automatically resolve cross-referrence
- it can automatically call the external programs depending on the typical packages loaded in the document
- it can execute appropriate programs in an appropriate order without an explicit specification of build procedure (arara cannot do this)
- its build procedure does not need to start with LaTeX (arara/latexmk cannot do this)
So, these can be briefly summarized in the beginning part. I enjoyed reading a thorough comparison, but not everyone feels the same and some are quite impatient. ;-)
| - [Events][events] | ||
| - [Comparison of Builders][] — A comparision of DiCy to [arara][] and | ||
| [latexmk][]. | ||
| - [Commands][] — The commands that can be passed to DiCy. |
There was a problem hiding this comment.
The terminology subcommand seems more common (e.g., google/subcommands, spf13/cobra, and maxogden/subcommand). So something like [Commands][] — A list of DiCy's subcommands is more simple.
There was a problem hiding this comment.
This is the only thing that I am probably not going to change right now even though I totally agree with you. Unfortunately I use the same terminology in the library API so I will need to do some code refactoring in order to change terminology. Therefore a separate PR will probably be needed.
There was a problem hiding this comment.
I understand the reason and agree that this should be a separate PR.
P.S. I really appreciate the built-in PythonTeX integration as I'll probably use PythonTeX in my thesis, which requires some add_cus_dep in latexmk. Thanks! 😄
There was a problem hiding this comment.
Cool! Let me know how it goes with PythonTeX or anything else in regards to DiCy.
README.md
Outdated
| @@ -104,6 +109,8 @@ commands should always be `load` and `save`, respectively. | |||
|
|
|||
| [appveyor]: https://ci.appveyor.com/project/yitzchak/dicy/branch/master | |||
|
|
|||
| [arara]: http://ctan.org/pkg/arara | |||
There was a problem hiding this comment.
Using HTTPS protocol when available is encouraged these days.
README.md
Outdated
| @@ -104,6 +109,8 @@ commands should always be `load` and `save`, respectively. | |||
|
|
|||
| [appveyor]: https://ci.appveyor.com/project/yitzchak/dicy/branch/master | |||
|
|
|||
| [arara]: http://ctan.org/pkg/arara | |||
|
|
|||
| [asymptote]: http://asymptote.sourceforge.net/ | |||
|
|
|||
| [biber]: http://biblatex-biber.sourceforge.net/ | |||
There was a problem hiding this comment.
Link to CTAN (https://www.ctan.org/pkg/biber) can be an option like arara or latexmk. CTAN page links to the SourceForge page.
docs/comparison-of-builders.md
Outdated
|
|
||
| There are many different automatic and semi-automatic builders for LaTeX-centric | ||
| documents. The [Compilation Topic][] at CTAN provides a current list of some of | ||
| those specifically designed for TeX or LaTeX documents. In addition there are |
There was a problem hiding this comment.
Pandoc internally uses LaTeX, but I don't understand the intention of mentioning pandoc here.
docs/comparison-of-builders.md
Outdated
|
|
||
| ## arara | ||
|
|
||
| [arara][] is a rule based builder which relies on directives given in the source |
There was a problem hiding this comment.
IMHO, link to external page only at the first appearance in the document is enough.
docs/comparison-of-builders.md
Outdated
|
|
||
| ## latexmk | ||
|
|
||
| [latexmk][] is rule based builder selects the appropriate programs to run |
docs/comparison-of-builders.md
Outdated
| explicit directives. For instance, to build a document with a BibTeX based | ||
| bibliography one need only execute the following in a command shell. | ||
|
|
||
| ```sh |
There was a problem hiding this comment.
Just FYI: you can also use shellsession or console lexers to show interactive shell input (ref.: atom/language-gfm#204)
docs/comparison-of-builders.md
Outdated
| latexmk -pdf foo.tex | ||
| ``` | ||
|
|
||
| Unlike [arara][], [latexmk][] uses the log files, console output and any file |
There was a problem hiding this comment.
I don't investigate the latexmk script, but does it parse console output in addition to log and other auxiliary files?
docs/comparison-of-builders.md
Outdated
| ``` | ||
|
|
||
| DiCy builds can be configured using command line options, using a YAML options | ||
| file or using TeX Magic comments. For instance, to enable shell escape and use a |
docs/comparison-of-builders.md
Outdated
|
|
||
| ```latex | ||
| %!TeX shellEscape = yes | ||
| %!TeX makeindexStyle = foo |
There was a problem hiding this comment.
This magic comment seems to change the MakeIndex's .ist file, not BibTeX.
|
Thanks @yudai-nkt! All really good comments especially the TL;DR summary! |
Resolves #85