Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Reach for Markdown, not LaTeX

blog.jez.io

Post reply on HN
Print view View original

121–130 of 184 posts

Re: Reach for Markdown, not LaTeX

#121

Post by tincholio »

marten-de-vries wrote: post #117
tincholio wrote: post #105

Earlier quoted context omitted.

\usepackage{listings} \begin{lstlisting} your code here \end{lstlisting} That's not much harder, is it? Plus, it has a ton of other functionalities you might want.

Now add syntax highlighting. In Markdown, it's trivial (```language-name), in LaTeX, you're going to have to define a style. LaTeX is more flexible, but it does come at a cost.

Maybe you should take a look here and disabuse yourself of that idea: https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings

Relevant bit:

    It supports the following programming languages:
    
    ABAP2,4, ACSL, Ada4, Algol4, Ant, Assembler2,4, Awk4, bash, Basic2,4, C#5, C++4, C4, Caml4, Clean, Cobol4, Comal, csh, Delphi, Eiffel, Elan, erlang, Euphoria, Fortran4, GCL, Gnuplot, Haskell, HTML, IDL4, inform, Java4, JVMIS, ksh, Lisp4, Logo, Lua2, make4, Mathematica1,4, Matlab, Mercury, MetaPost, Miranda, Mizar, ML, Modelica3, Modula-2, MuPAD, NASTRAN, Oberon-2, Objective C5 , OCL4, Octave, Oz, Pascal4, Perl, PHP, PL/I, Plasm, POV, Prolog, Promela, Python, R, Reduce, Rexx, RSL, Ruby, S4, SAS, Scilab, sh, SHELXL, Simula4, SQL, tcl4, TeX4, VBScript, Verilog, VHDL4, VRML4, XML, XSLT.
    
    For some of them, several dialects are supported. For more information, refer to the documentation that comes with the package, it should be within your distribution under the name listings-*.dvi.
    
    Notes
    
        1 It supports Mathematica code only if you are typing in plain text format. You can't include *.NB files \lstinputlisting{...} as you could with any other programming language, but Mathematica can export in a pretty-formatted LaTeX source.
        2 Specification of the dialect is mandatory for these languages (e.g. language={[x86masm]Assembler}).
        3 Modelica is supported via the dtsyntax package available here.
        4 For these languages, multiple dialects are supported. C, for example, has ANSI, Handel, Objective and Sharp. See p. 12 of the listings manual for an overview.
        5 Defined as a dialect of another language
If you want to get fancier, and have pygments in your system, you can use the minted package, instead.

Re: Reach for Markdown, not LaTeX

#122

Post by akalin »

royal_ts wrote: post #110
black_knight wrote: post #109

Pandoc is really awesome. Even mathematics papers can be written in (mostly) markdown, and then converted to latex before compiling to PDF. For mathematics I would also recommend using Unicode symbols in place of LaTeX commands, which makes the source even more readable. For instance $∏_{x∈X} ∑_{y∈Y} Ψ(x,y) → ∑_{f : X → Y} ∏_{x∈Y} Ψ(x,y)$ instead of $\prod_{x \in X} \sum_{y \in Y} \Psi(x,y) \to \sum_{f : X \to Y} \pr…

But you can type the second one way easier

Not necessarily -- with the right editor, e.g. Emacs, you can have it automatically convert "\alpha" to "α" (built-in TeX input mode), or if you're using AUCTeX, you can type "`a", which would be easier than "\alpha" or "α"!

Edit: Oops, saw the sibling post. That also works, although sadly I can't take always advantage of that since I'm not always on Linux.

Re: Reach for Markdown, not LaTeX

#123

Post by [deleted] »

bo1024 wrote: post #62
kerkeslager wrote: post #49

Earlier quoted context omitted.

I'd also add that while Markdown and LaTeX can do some of the same things, they're designed toward very different tasks. I've used both numerous times in my career, and I can't remember a case where it's been ambiguous which tool was more appropriate for the task. If it's going to be printed, you probably want LaTeX. If it's going to be rendered to a screen, you probably want Markdown. If it's going to be rendered to…

When you say "rendered to a screen", do you really mean "placed on a webpage"? PDFs generated by LaTeX are rendered to screen all the time. edit: Actually, I find that I completely agree with your point if "printed" is replaced by "shared in pdf format" and "rendered to screen" is replaced by "shared in plain text or HTML format".

[deleted]

Re: Reach for Markdown, not LaTeX

#124

Post by ptspts »

delhanty wrote: post #71
kerkeslager wrote: post #49

Earlier quoted context omitted.

I'd also add that while Markdown and LaTeX can do some of the same things, they're designed toward very different tasks. I've used both numerous times in my career, and I can't remember a case where it's been ambiguous which tool was more appropriate for the task. If it's going to be printed, you probably want LaTeX. If it's going to be rendered to a screen, you probably want Markdown. If it's going to be rendered to…

(In addition / As an alternative) to Pandoc, has anyone tried Bookish [0] by Terrence Parr of ANTLR fame? It was referenced by Jeremy Howard in a HN comment [1] on the submission for their "Matrix Calculus for Deep Learning " HN submission of 18 days ago [2]: >Jeremy here. Here to answer any questions or comments that you have. > >But more importantly - I need to mention that Terence Parr did nearly all the work on t…

FYI bookish embeds math formulas as vector images (SVG) to the generated HTML.

Re: Reach for Markdown, not LaTeX

#125

Post by da_chicken »

hyperbovine wrote: post #56
da_chicken wrote: post #20

Earlier quoted context omitted.

My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or a Wiki for things like process or project documentation. Programmers love to use LaTeX, because they get to feel like they're doing something exciting like writing a computer program when what they're actually doing something incredibly boring like writing do…

Wow, this is just so far off the mark I don't even know where to begin. LaTeX excels in three areas that are crucial for writing complex documents -- cross references, citations, and indexing. You clearly have not had to endure the house of horrors that is the MS Word ToC, or trying to get autonumbering working as you wish for sections, figures, and tables, or managing a large (100s of pages) multipart document, or a…

You don't know the requirements of documentation that we're writing. They don't need a table of contents. They don't need an index. They don't need citations. They don't need math symbols. They don't need tables more complex than a word processor can create. We require no features which your typical academic or research paper requires. We are documenting processes with screenshots that users can refer to in order to accomplish specific tasks. Only a dozen of them are more than 25 pages, and in Word if you keep your document formatting simple and use the built-in styles for headings, the Navigation Pane serves as a hyperlinked ToC. None of these documents should be printed because the processes can change, so beyond basic structure, layout isn't particularly important.

Furthermore, our documents can't be written in LaTeX because half the people responsible for maintaining them come from a non-technical background with no experience in programming. No, we are not going to inflict a WYSIWYG LaTeX editor -- all of which are far less usable than Word -- on people just because some technical people want to pretend they're programming.

Nevertheless, our CS interns invariably say, "Why don't we use LaTeX for this documentation?" I understand why they want to. They use LaTeX for all their papers. However, it is inappropriate in our situation and has gotten to be a rather irritating question.

Re: Reach for Markdown, not LaTeX

#126

Post by da_chicken »

hueving wrote: post #28
da_chicken wrote: post #20

Earlier quoted context omitted.

My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or a Wiki for things like process or project documentation. Programmers love to use LaTeX, because they get to feel like they're doing something exciting like writing a computer program when what they're actually doing something incredibly boring like writing do…

>Documentation is meant to be read by everyone, not make you feel good about being forced to write it. I think you missed the point you were trying to make here because nobody has any difficulty reading the PDFs rendered from latex.

Yes, but maintaining documentation in PDF is not.

Half the people that manage our doc are non-programmers. They're not learning LaTeX. They're not editing raw PDFs while the other half of the team uses LaTeX.

Re: Reach for Markdown, not LaTeX

#127

Post by marten-de-vries »

tincholio wrote: post #121
marten-de-vries wrote: post #117

Earlier quoted context omitted.

Now add syntax highlighting. In Markdown, it's trivial (```language-name), in LaTeX, you're going to have to define a style. LaTeX is more flexible, but it does come at a cost.

Maybe you should take a look here and disabuse yourself of that idea: https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings Relevant bit: It supports the following programming languages: ABAP2,4, ACSL, Ada4, Algol4, Ant, Assembler2,4, Awk4, bash, Basic2,4, C#5, C++4, C4, Caml4, Clean, Cobol4, Comal, csh, Delphi, Eiffel, Elan, erlang, Euphoria, Fortran4, GCL, Gnuplot, Haskell, HTML, IDL4, inform, Java4, JVMIS, ksh,…

Ah, seems like the situation is better than I remembered. I confused colored syntax highlighting with the default settings, which highlight using font weight/italicness etc.

I did try minted once, but never used it in practice. The dependency on pygments making the documents more system dependent is less than ideal.

Re: Reach for Markdown, not LaTeX

#128

Post by ptspts »

hyperbovine wrote: post #56
da_chicken wrote: post #20

Earlier quoted context omitted.

My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or a Wiki for things like process or project documentation. Programmers love to use LaTeX, because they get to feel like they're doing something exciting like writing a computer program when what they're actually doing something incredibly boring like writing do…

Wow, this is just so far off the mark I don't even know where to begin. LaTeX excels in three areas that are crucial for writing complex documents -- cross references, citations, and indexing. You clearly have not had to endure the house of horrors that is the MS Word ToC, or trying to get autonumbering working as you wish for sections, figures, and tables, or managing a large (100s of pages) multipart document, or a…

Anecdote about LibreOffice 4.2.8.2: Due to a bug, LibreOffice was generating incorrect page numbers in the table of contents of a 80-page document: some sections were 1 page off, even right after I clicked to manually regenerate the TOC.

It was very frustrating, because I noticed it just a few hours before the deadline. To work around of this bug, I had to insert manual page breaks (mostly randomly), and I had to make the vertical margins of the TOC pages smaller.

LaTeX has always generated the correct numbers in the last 25 years I've been using it. And if I got something unexpected, I was able to fix it for good (without document-specific hacks such as manual page breaks) by adding some macro calls. With LibreOffice and Microsoft Office, getting such a fix ready in 1 hour is hopeless for me, so I'll either miss the deadline or I hand in something incorrect and unprofessional.

Also: LibreOffice doesn't support character formatting (of a few words only) in the ToC. LibreOffice doesn't support omitting a few select sections from the ToC. LaTeX supports both.

Re: Reach for Markdown, not LaTeX

#129

Post by da_chicken »

greenleafjacob wrote: post #52
da_chicken wrote: post #20

Earlier quoted context omitted.

My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or a Wiki for things like process or project documentation. Programmers love to use LaTeX, because they get to feel like they're doing something exciting like writing a computer program when what they're actually doing something incredibly boring like writing do…

Do you think legal writing falls into this category?

As far as I'm aware, the vast majority of legal documents are still written with Word or Google Docs. Nearly everybody went to Word when WordPerfect died.

Re: Reach for Markdown, not LaTeX

#130

Post by mbid »

I don't get it. Say I already know that I'll need some formulae in my document. Then the use case here seems to be, essentially, that I can write

    # Section Name
instead of

    \section{Section Name}
and that I can write

    *important stuff*
instead of

    \emph{important stuff}.
I can see that the markdown version is a little nicer on the eyes and keyboard, but only by a small margin.

Now, if I write a document in latex I need to understand exactly

* latex.

Latex is a beast, but there are no serious alternatives to typeset formulae.

If I want to write markdown with some latex in it, I need to understand

* markdown

* latex

* how pandoc interleaves the two.

What if, as will inevitably be the case, something breaks? There will not even be close to as much documentation for the markdown+latex+pandoc stack as for the latex-only stack out there. Is there even a standard for markdown+latex, the pandoc way?

Then there's the issue of packages needed to compile. Tex suites are already huge pieces of software. Now I also need to have pandoc. Pandoc is written in haskell, and the haskell stack on arch is a complete clusterfuck. I will not have saved time if I need to understand how to fix pandoc if it breaks after an update. Granted, this is mostly an arch issue, but the point is that the more software you use, the more likely it is that something breaks.

The bottom line is that you replace an already complicated piece of software with the exact same piece of software and then something. I find it hard to justify it in this case where there is so little benefit.

Post reply on HN