Support for LaTeX

[jirutka]

@jxxcarlson I’ve prepared some basic support for LaTeX backend in the latex branch. The only added file is doctest/latex/examples_suite (DocTest::Latex::ExamplesSuite) and its spec.

ExamplesSuite class is responsible for parsing and serializing of example groups in a particular format (e.g. HTML, LaTeX…). Examples group is a file that may contain many examples (it’s described here). Each example is delimited with a header that must contain the name (identifier) and optionally description and options (see example). ExamplesSuite#parse must parse the example’s header (i.e. name, options…) and read (not parse!) the actual content. It doesn’t matter what the content is at this moment (if LaTeX or HTML), but it must be distinguishable from the header.

In the case of AsciiDoc (example) and HTML (example) I’ve decided to write header as a comment, so the examples group file is a valid AsciiDoc and HTML document respectively (you know, for syntax highlighting and stuff like that). Backend typically doesn’t produce comments, so it’s okay here. Not in your case though. Your backend is producing a lot of commented boilerplate, so we have to agree on some special syntax to distinguish a regular LaTeX comment from the example’s header.

I’m thinking about something like this:

%====
% .first_example
% Each example must be preceded by a header (comment); the first line must
% contain the example’s name prefixed with a dot. This text is interpreted
% as a description.
%====
The example’s content in \textbf{LaTeX}.

The trailing new line (below this) will be removed.

%====
% .second_example
% You may also specify options for comparing or Asciidoctor renderer. Option
% line starts with a semicolon, then comes the option name ended by a
% semicolon and after that the option’s value (may be omitted for boolean
% options).
% :option_1: value 1
% :option_2: value 1
% :option_2: value 2
% :boolean_option:
%====
\begin{enumerate}
  \item The first item
  \item The second item
  \item The third etc \ldots
\end{enumerate}

What do you think? Won’t it interfere with some LaTeX syntax that you may use in your backend?

---

For the record, this discussion started in https://github.com/asciidoctor/asciidoctor-latex/pull/13.

[jirutka]

Hm, I don’t like about this style that it’s too verbose in the most common case (name only):

%====
% .strong
%====
\textbf{chunky bacon}

[jirutka]

Gentle reminder, @jxxcarlson.

[jxxcarlson]

I've merged #2, pulled it back to my machine and ran several files in try-out through asciidoctor. All OK.

[jirutka]

This comment belongs to https://github.com/jxxcarlson/asciidoctor-latex/pull/2, isn’t it?

[jxxcarlson]

Correct.

[jirutka]

I’ve changed syntax of the example’s header to be more specific — to not interfere with regular comments produced by the backend (see ace99e9fe25a4d20af0da5d1bba664903e8ed6fb):

Format of the example's header:

%== .example_name
% Any text that is not the example's name or an option is considered
% as a description.
% :option_1: value 1
% :option_2: value 1
% :option_2: value 2
% :boolean_option:
%==
The example's content in \LaTeX.

The trailing new line (below this) will be removed.

Format of the example's header with name only:

%== .example_name ==%
The example's content in \LaTeX.

To use it in test:

class TestBackend < DocTest::Test
  renderer_opts backend_name: :latex
  generate_tests! DocTest::Latex::ExamplesSuite
end

The next thing we have to solve is how to remove LaTeX boilerplate from examples. I’ll write more later.

[jxxcarlson]

Agreed on LaTeX boilerplate. That was really bothering me.