When I create an ePub file with pandoc for export to Kindle MOBI
format, naming a style sheet on the command line causes each chapter in the table of contents to be preceded by a number. Given files 1.md and 2.md with h1 headers Chapter 1 and Chapter 2, the generated TOC looks like this,
but only if you include a style sheet using --epub-stylesheet:
1. Chapter 1
2. Chapter 2
Command line that causes the problem:
$ pandoc --table-of-contents --epub-stylesheet=epub.css *.md title.yaml -o foo.epub
If I do the same thing without specifying a style sheet, it doesn't happen:
$ pandoc --table-of-contents *.md title.yaml -o foo.epub
The generated table of contents then looks like this, which is what I want:
Chapter 1
Chapter 2
It doesn't matter what the contents of the style sheet are. It happens even when it is completely empty.
Contents of file 1.md:
# Chapter 1
hello, world.
Contents of file 2.md:
# Chapter 2
Oh, I love Chapter 2!
Contents of file epub.css:
/* Empty */
Contents of file title.yaml:
---
title: 'My book'
author: 'Author name'
rights: © 2017 by Author
lang: en-US
...
By using --epub-stylesheet you provide your own CSS stylesheet instead of the default one. You'll have to copy the styles you want to keep fron the pandoc's default epub.css, namely:
ol.toc { padding: 0; margin-left: 1em; }
ol.toc li { list-style-type: none; margin: 0; padding: 0; }
Related
I am creating a quarto book project in RStudio to render an html document.
I need to specify some parameters in the yml file but the qmd file returns
"object 'params' not found". Using knitR.
I use the default yml file where I have added params under the book tag
project:
type: book
book:
title: "Params_TEst"
author: "Jane Doe"
date: "15/07/2022"
params:
pcn: 0.1
chapters:
- index.qmd
- intro.qmd
- summary.qmd
- references.qmd
bibliography: references.bib
format:
html:
theme: cosmo
pdf:
documentclass: scrreprt
editor: visual
and the qmd file looks like this
# Preface {.unnumbered}
This is a Quarto book.
To learn more about Quarto books visit <https://quarto.org/docs/books>.
```{r}
1 + 1
params$pcn
When I render the book, or preview the book in Rstudio the error I receive is:
Quitting from lines 8-10 (index.qmd)
Error in eval(expr, envir, enclos) : object 'params' not found
Calls: .main ... withVisible -> eval_with_user_handlers -> eval -> eval
I have experimented placing the params line in the yml in different places but nothing works so far.
Could anybody help?
For multi-page renders, e.g. quarto books, you need to add the YAML to each page, not in the _quarto.yml file
So in your case, each of the chapters that calls a parameter needs a YAML header, like index.qmd, intro.qmd, and summary.qmd, but perhaps not references.qmd.
The YAML header should look just like it does in a standard Rmd. So for example, your index.qmd would look like this:
---
params:
pcn: 0.1
---
# Preface {.unnumbered}
This is a Quarto book.
To learn more about Quarto books visit <https://quarto.org/docs/books>.
```{r}
1 + 1
params$pcn
But, what if you need to change the parameter and re-render?
Then simply pass new parameters to the quarto_render function
quarto::quarto_render(input = here::here("quarto"), #expecting a dir to render
output_format = "html", #output dir is set in _quarto.yml
cache_refresh = TRUE,
execute_params = list(pcn = 0.2))
For now, this only seems to work if you add the parameters to each individual page front-matter YAML.
If you have a large number of pages and need to keep parameters centralized, a workaround is to run a preprocessing script that replaces the parameters in all pages. To add a preprocessing script, add the key pre-render to your _quarto.yml file. The Quarto website has detailed instructions.
For example, if you have N pages named index<N>.qmd, you could have a placeholder in the YML of each page:
---
title: This is chapter N
yourparamplaceholder
---
Your pre-render script could replace yourparamplaceholder with the desired parameters. Here's an example Python script:
for filename in os.listdir(dir):
if filename.endswith(".qmd"):
with open(filename, "r") as f:
txt = f.read()
f.replace('yourparamplaceholder', 'params:\n\tpcn: 0.1\n\tother:20\n')
with open(filename, "w") as ff:
ff.write(txt)
I agree with you that being able to set parameters centrally would be a good idea.
This script is part of a legacy code that runs to create a GUI interface for editing text files to be used in analysis codes. There is a windows command script that references a ".sed" file which controls the formatting, editing, and help menu for the GUI. I would like to identify the coding language/rules used in these ".sed" files so that I can make a new more complicated input text file with descriptions of inputs.
Ideally, I would like to be able to use this code to create/edit ".csv" files which can be edited in Excel. This would potentially mean needing to avoid the set variable sizes/padding in the #file block of code below.
Any googling attempts to find more about the coding result in unix sed instructions that are not helpful.
UPDATE: I did find an additional exe in the shell folder of the legacy code for "sedwin.exe". When googled this seems to refer to an old "SEDT text editor for MS-DOS".
An example section from a ".sed" file is below:
<code>
#rem( version description information here )
#version(){"2.0"}
%--------------------------------------------------------------------
#file(seal2,native){
title1(A80);
title2(A80);
title3(A80);
r(G10),del(A1),ll(G10),c(G10),lg(G10),dg(G10),ngroov(I10);
ncase(I10),necc(I10),necase(I10),#for(i,1,necase,0){entlos[i](G10)};
#for(i,1,ncase,0){
speed[i](G10),ro[i](G10),nu[i](G10),delp[i](G10);
}
}
#edit(seal2){
#prompted(22,5,"SEAL2 Input Data"){
#help(){
" Code Name Here
"",
"Code description here"
};
#icon("Titles",titles){#titles();}
#icon("Seal Parameters",seal){#seal();}
#icon("Speed, Fluid Parameters",cases){#cases();}
}
}
#titles(){
#prompted(1,7,"Three Title Lines"){
#help(){
"These title lines will appear on the output of",
"the program.",
"",
"They are useful for identifying the output but",
"do not directly affect the results."
};
#datum("",title1,75,"");
#datum("",title2,75,"");
#datum("",title3,75,"");
}
}
#seal(){
#prompted(12,8,"Seal Parameters"){
#help(){
"Descriptions of inputs in this window.",
};
#datum("Shaft Radius (in)",r,15,"0.");
#float_check("Must be > 0.0","(%g)>0.");
#datum("Land Length (in)",ll,15,"0.");
#float_check("Must be > 0.0","(%g)>0.");
#datum("Seal Radial Clearance (in)",c,15,"0.");
#float_check("Must be > 0.0","(%g)>0.");
#datum("Groove Length (in)",lg,15,"0.");
#float_check("Must be >= 0.0","(%g)>=0.");
#datum("Groove Depth (in)",dg,15,"0.");
#float_check("Must be >= 0.0","(%g)>=0.");
#datum("Number of Grooves (0=plain seal)",ngroov,15,"0");
#int_check("Must be >= 0","(%d)>=0");
#datum("Number of Eccentricities",necc,15,"1");
#int_check("Must be between 1 and 10","(%d)>0&&(%d)<11");
#icon("Entrance Loss Cases",losses){#losses();}
}
}
#new_file(seal2){
file_type=seal2;
unit_type=native;
titles=New;
title1=;
title2=;
title3="(SEAL2 Data File)";
del=",";
seal=New;
ll=0.0;
r=0.0;
c=0.0;
lg=0.0;
dg=0.0;
ngroov=0;
losses=New;
necc=1;
necase=1;
entlos[1...necase]=0.1;
cases=New;
ncase=1;
speed[1...ncase]=0.0;
delp[1...ncase]=0.0;
nu[1...ncase]=0.0;
ro[1...ncase]=0.0;
}
</code>
After hakyll-init, it creates an example template.
This is pretty much base on index.html file
---
title: Home
---
<h2>Hello</h2>
<img src="/images/haskell-logo.png" style="float: right; margin: 10px;" />
<p>Welcome to my blog!</p>
<p>I've reproduced a list of recent posts here for your reading pleasure:</p>
<h2>Posts</h2>
$partial("templates/post-list.html")$
<p>…or you can find more in the archives.</p>
I just wonder what if I want to show a whole markdown file after Hello? After the <h2>Hello</h2>, can I show the article from a markdown file.
I tried to add $body$ in there, but the body embed another index.html inside this index.html
How to replace this $body$ and let it show article from markdown file?
The default match "index.html" only apply templates/default.html. Is it possible apply it to templates/post.html, so it will allow the $body$ to show markdown article.
match "index.html" $ do
route idRoute
compile $ do
posts <- recentFirst =<< loadAll "posts/*"
let indexCtx =
listField "posts" postCtx (return posts) `mappend`
defaultContext
getResourceBody
>>= applyAsTemplate indexCtx
>>= loadAndApplyTemplate "templates/default.html" indexCtx
>>= relativizeUrls
I am using doxygen + breathe + Sphinx to document C source code.
In my conf.py I have set:
breathe_show_define_initializer = True
and
html_theme = 'sphinx_rtd_theme'
In my C source code I have defines such as:
#define FOO 12U //!< example #define
In the xml generated from doxygen, I see:
<name>FOO</name>
<initializer>12U</initializer>
<briefdescription>
<para>example #define </para>
</briefdescription>
So far so good!
The problem is the output from Sphinx is missing white space between the name and the initializer. i.e. as shown, no space between FOO and 12U:
FOO12U
example #define
I tried using both:
.. doxygendefine:: FOO
and I tried the group which has a number of defines:
.. doxygengroup:: MY_DEFINES_GROUP
If I change html_theme = 'alabaster'
Then there is a space between FOO and 12U
Any thoughts - am I missing a configuration?
I found this question via Google since I ran into the same issue. I'm posting my solution here which I hacked up and it seems to work for my case in the hopes of saving someone else time. My solution was to insert a "no break space" after each name of the define (but before the value).
Create a custom css: under _static/custom-signame.css (which is where I store my other custom css files)
The contents of the file are:
/* add a space to fix Breathe+Sphinx rtd_theme with
breathe_show_define_initializer */
.sig-name::after {
content: "\00a0";
}
Make sure that conf.py is updated to include the new custom css created in step 2:
html_static_path = ['_static']
html_css_files = [
'custom-table.css',
'custom-signame.css',
]
Suppose I have two files a.rst and b.rst in the same folder, and a.rst looks like this
.. _foo: http://stackoverflow.com
`foo`_ is a website
It seems using foo in b.rst is not allowed. Is there a way to define hyperlinks and use them in multiple files?
Followup
I used the extlinks extension as Steve Piercy suggested. Its implementation and docstring can be seen here on github.
In my case, I define wikipedia link in my conf.py
extlinks = {'wiki': ('https://en.wikipedia.org/wiki/%s', '')}
and in the .rst files, use them like
:wiki:`Einstein <Albert_Einstein>`
where Einstein will be displayed as a link to https://en.wikipedia.org/wiki/Albert_Einstein
There are at least four possible solutions.
1. repeat yourself
Put your complete reST in each file. You probably don't want that.
2. combined rst_epilog and substitution
This one is clever. Configure the rst_epilog value, in your conf.py along with a substition with the replace directive:
rst_epilog = """
.. |foo| replace:: foo
.. _foo: http://stackoverflow.com
"""
and reST:
|foo|_ is a website
yields:
<a class="reference external" href="http://stackoverflow.com">foo</a>
3. extlinks
For links to external websites where you want to have a base URL and append path segments or arguments, you can use extlinks in your conf.py:
extensions = [
...
'sphinx.ext.extlinks',
...
]
...
extlinks = {'so': ('https://stackoverflow.com/%s', None)}
Then in your reST:
:so:`questions/49016433`
Yields:
<a class="reference external"
href="https://stackoverflow.com/questions/49016433">
https://stackoverflow.com/questions/49016433
</a>
4. intersphinx
For external websites that are documentation generated by Sphinx, then you can use intersphinx, in your conf.py:
extensions = [
...
'sphinx.ext.intersphinx',
...
]
...
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
}
Then in your reST:
:py:mod:`doctest`
Yields:
<a class="reference external"
href="https://docs.python.org/3/library/doctest.html#module-doctest"
title="(in Python v3.6)">
<code class="xref py py-mod docutils literal">
<span class="pre">doctest</span>
</code>
</a>
This might come a bit late but I have found a solution that works very neatly for me and it is not among the answers already given.
In my case, I create a file with all the links used in my project, save it as /include/links.rst, and looking something like:
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
.. _googledoc: https://google.github.io/styleguide/pyguide.html
Then there are the files a.rst and b.rst looking like:
.. include:: /include/links.rst
File A.rst
##########
Click `here <PEP8_>`_ to see the PEP8 coding style
Alternatively, visit either:
- `Numpy Style <numpydoc_>`_
- `Google Style <googledoc_>`_
and
.. include:: /include/links.rst
File B.rst
##########
You can visit `Python's PEP8 Style Guide <PEP8_>`_
For docstrings, you can use either `Numpy's <numpydoc_>`_ or `Google's <googledoc_>`_
respectively.
The produced output for both cases is:
and
respectively.
Moreover, I would like to emphasize the fact of which I was actually really struggling to achieve, to use different names (displayed text) for the same link at different locations and which I have achieved with the double _, one inside the <..._> and another outside.
This is another solution: it is a bit hacky and a little bit different respect to the officially supported way to share external links.
First complete the Setup then:
in conf.py add the commonlinks entry in extensions
in conf.py configure the map of common links:
For example:
extensions = [
...,
'sphinx.ext.commonlinks'
]
commonlinks = {
'issues': 'https://github.com/sphinx-doc/sphinx/issues',
'github': 'https://github.com'
}
Then in .rst files you can do these:
The :github:`_url_` url is aliased to :github:`GitHub` and also to :github:`this`
Setup
All that is needed is to copy into sphinx/ext directory the file commonlinks.py:
# -*- coding: utf-8 -*-
"""
sphinx.ext.commonlinks
~~~~~~~~~~~~~~~~~~~~~~
Extension to save typing and prevent hard-coding of common URLs in the reST
files.
This adds a new config value called ``commonlinks`` that is created like this::
commonlinks = {'exmpl': 'http://example.com/mypage.html', ...}
Now you can use e.g. :exmpl:`foo` in your documents. This will create a
link to ``http://example.com/mypage.html``. The link caption depends on the
role content:
- If it is ``_url_``, the caption will be the full URL.
- If it is a string, the caption will be the role content.
"""
from six import iteritems
from docutils import nodes, utils
import sphinx
from sphinx.util.nodes import split_explicit_title
def make_link_role(base_url):
def role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
if text == '_url_':
title = base_url
else:
title = text
pnode = nodes.reference(title, title, internal=False, refuri=base_url)
return [pnode], []
return role
def setup_link_roles(app):
for name, base_url in iteritems(app.config.commonlinks):
app.add_role(name, make_link_role(base_url))
def setup(app):
app.add_config_value('commonlinks', {}, 'env')
app.connect('builder-inited', setup_link_roles)
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
To locate the sphinx installation directory one way is:
$ python 3
> import sphinx
> sphinx
<module 'sphinx' from '/usr/local/lib/python3.5/dist-packages/sphinx/__init__.py'>
then:
% cp commonlinks.py /usr/local/lib/python3.5/dist-packages/sphinx/ext