I am creating an asciidoc as described below:
Start of document
* R{counter:recom}: sentence1
...
* R{counter:recom}: sentence2
...
* R{counter:recom}: sentence3
End
Note: The R{counter:recom} from the asciidoc will be displayed as R1 R2 R3 in the resulting document.
I need to create a table at the start of the document which will refer the counters and text form the doc as described below:
Start of document
|Ref#|text from the document
|R1|sentence1
|R2|sentence2
|R3|sentence3
throughout the doc:
* R{counter:recom}: sentence1
...
* R{counter:recom}: sentence2
...
* R{counter:recom}: sentence3
End
Now, there are 2 unknown things here:
How do I refer the counter and sentence part from the asciidoc R1 sentence1 in the table together or separately so that, if I change it in the doc it will be changed in the table?
How do I refer the counter values in the table so that they work as links to the actual counter value R1 in the doc?
Not sure there is a readymade construct to achieve this and I haven't figured out how can I achieve it using an anchor or include statement.
What #ahus1 said.
Or, if you can convert your counter lines into section titles, then it's easy:
= Document
[cols="a"]
|===
| <<first>>
| <<second>>
| <<third>>
|===
...
[[first]]
== R{counter:recom}: sentence 1
...
[[second]]
== R{counter:recom}: sentence 2
...
[[third]]
== R{counter:recom}: sentence 3
...
End
The following is an experiment with attributes. It fulfills the following requirements:
if you change the sentence in the attribute, it will be changed in both the table and the doc
the table and the doc will contain the same number
the table to the item in the document
:ref-a: R{counter:recom}
:sen-a: sentence1
:ref-b: R{counter:recom}
:sen-b: sentence2
:ref-c: R{counter:recom}
:sen-c: sentence3
|===
|Ref#|text from the document
|<<link-a>>|{sen-a}
|<<link-b>>|{sen-b}
|<<link-c>>|{sen-c}
|===
throughout the doc:
* [[link-a,{ref-a}]]{ref-a}: {sen-a}
...
* [[link-b,{ref-b}]]{ref-b}: {sen-b}
...
* [[link-c,{ref-c}]]{ref-c}: {sen-c}
...
rendering this with either
Asciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (jruby 9.2.7.0 (2.5.3) 2019-04-09 8a269e3 Java HotSpot(TM) 64-Bit Server VM 25.161-b12 on 1.8.0_161-b12 +jit [mswin32-x86_64]) (lc:CP850 fs:Windows-1252 in:CP850 ex:CP850)
or
Asciidoctor PDF 1.5.0.beta.1 using Asciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (jruby 9.2.7.0 (2.5.3) 2019-04-09 8a269e3 Java HotSpot(TM) 64-Bit Server VM 25.161-b12 on 1.8.0_161-b12 +jit [mswin32-x86_64]) (lc:CP850 fs:Windows-1252 in:CP850 ex:CP850)
displays
Alternative to putting the sentence in an attribute: assuming that each chapter is described in a separate file, you can use an include statement that only includes the first line of the file for the table using include::filename.txt[lines=1], and later include the full file inside the document. See Include By Line Ranges in the Asciidoctor documentation for details (you can also use tags to specify the contents for the table).
Related
I am having so much trouble getting this syntax to translate - Angular 13.0.02 .
My two resources are:
https://angular.io/api/localize/init/$localize
https://lokalise.com/blog/angular-i18n/
As per the Angular docs:
Naming placeholders
If the template literal string contains expressions, then the expressions will be automatically associated with placeholder names for you.
For example:
$localize `Hi ${name}! There are ${items.length} items.`;
will generate a message-source of Hi {$PH}! There are {$PH_1} items.`
And providing meaning, descrip, and ID:
$localize`:meaning|description##id:source message text`;
$localize`:meaning|:source message text`;
$localize`:description:source message text`;
$localize`:##id:source message text`;
This example from lokalise.com works:
const company = "Google";
const created_by = $localize`Created by ${company}`;
in my XLIF translation file:
<trans-unit id="3990133897753911565" datatype="html">
<source>Created by <x id="PH"/></source>
<target>Creado por... <x id="PH"/></target>
</trans-unit>
This DOESN'T WQRK:
Yet when I try to reproduce the same syntax with another i18 term - it DOESN'T WORK. It only pulls the English phrase, not the Spanish one.
const company = "Google";
const createdByCompany = $localize`Created by this person ${company}`;
<trans-unit id="spanishTest123" datatype="html">
<source>Created by this person <x id="PH"/></source>
<target>Creado por esta persona <x id="PH"/></target>
</trans-unit>
FYI: for the example that does work, if I REMOVE id="3990133897753911565", then it does NOT pull that translation. So clearly this id makes it happen - yet in my 2nd example I cannot get it to work.
*** UPDATE ***
Using the Angular extract tool produces the XLF file in the required xml format (it parses all i18n tags in your html temples, and the $localize calls in your component code). Run in your app's root dir as follows ng extract-i18n --output-path src/locale - then check the messages.xlf file in the locale folder.
So as per the docs, the "pre-pending it with a colon" syntax did work - https://angular.io/api/localize/init/$localize
const msg = $localize`:Password Reset Modal|Min num of chars##passwordNumChars:Must be at least ${setting.SettingValue}:minLen: characters long.`;
Notice how I updated the trans-unit "id" attrib in the xlf - i.e. my custom ID is "passwordNumChars".
<trans-unit id="passwordNumChars" datatype="html">
<source>Must be at least <x id="minLen" equiv-text="setting.SettingValue"/> characters long.</source>
<target>Debe contener al menos <x id="minLen" equiv-text="setting.SettingValue"/> caracteres.</target>
<note priority="1" from="meaning">password edit modal</note>
</trans-unit>
One final note: if you have the $localize function setup in your ts code - but you can't figure out the xlf format - you can use ng extract-i18n --output-path src/locale from a cmd line to generate the appropriate xlf file.
Then just copy/paste the section you need into your locale file; also perhaps into whatever translation software you're using as the source of truth (i.e. poedit.com to store all i18n terms).
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
libxml2 (for C) is not preserving empty elements in their original form on a save. It replaces <tag></tag> with <tag/> which is technically correct but causes problems for us.
xmlDocPtr doc = xmlParseFile("myfile.xml");
xmlNodePtr root = xmlSaveFile("mynewfile.xml", doc);
I've tried playing with the various options (using xlmReadFile) but none seem to affect the output. One post here mentioned disabling tag compression but the example was for PERL and I've found no analog for C.
Is there an option to disable this behavior?
Just found this enum in the xmlsave module documentation:
Enum xmlSaveOption {
XML_SAVE_FORMAT = 1 : format save output
XML_SAVE_NO_DECL = 2 : drop the xml declaration
XML_SAVE_NO_EMPTY = 4 : no empty tags
XML_SAVE_NO_XHTML = 8 : disable XHTML1 specific rules
XML_SAVE_XHTML = 16 : force XHTML1 specific rules
XML_SAVE_AS_XML = 32 : force XML serialization on HTML doc
XML_SAVE_AS_HTML = 64 : force HTML serialization on XML doc
XML_SAVE_WSNONSIG = 128 : format with non-significant whitespace
}
Maybe you can refactor your application to use this module for serialization, and play a little with these options. Specially with XML_SAVE_NO_EMPTY.
Your code may look like this:
xmlSaveCtxt *ctxt = xmlSaveToFilename("mynewfile.xml", "UTF-8", XML_SAVE_FORMAT | XML_SAVE_NO_EMPTY);
if (!ctxt || xmlSaveDoc(ctxt, doc) < 0 || xmlSaveClose(ctxt) < 0)
//...deal with the error
What is the best way to handle the lack of a namespace on some of the nodes in an xml document using lxml? Should I first modify all None named nodes to add the "gmd" name and then change the tree attributes to name http://www.isotc211.org/2005/gmd as "gmd"? If so, is there a clean way to do this with lxml or something else that would be relatively clean/safe?
from lxml import etree
nsmap = charts_tree.nsmap
nsmap.pop(None) # complains without this on the xpath with
# TypeError: empty namespace prefix is not supported in XPath
len (charts_tree.xpath('//*/gml:Polygon',namespaces=nsmap))
# 1180
len (charts_tree.xpath('//*/DS_DataSet',namespaces=nsmap))
# 0 ... Bummer!
len (charts_tree.xpath('//*/DS_DataSet'))
# 0 ... Also a bummer
e.g. http://www.charts.noaa.gov/ENCs/ENCProdCat_19115.xml
<DS_Series xmlns="http://www.isotc211.org/2005/gmd" xmlns:gco="http://www.isotc211.org/2005/gco" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:gsr="http://www.isotc211.org/2005/gsr" xmlns:gss="http://www.isotc211.org/2005/gss" xmlns:gts="http://www.isotc211.org/2005/gts" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.isotc211.org/2005/gmd http://schemas.opengis.net/iso/19139/20070417/gmd/gmd.xsd">
<composedOf>
<DS_DataSet>
<has>
<MD_Metadata>
<parentIdentifier>
<gco:CharacterString>NOAA ENC Product Catalog</gco:CharacterString>
</parentIdentifier>
...
<EX_BoundingPolygon>
<polygon>
<gml:Polygon gml:id="US1AK90M_P1">
<gml:exterior>
<gml:LinearRing>
<gml:pos>67.61505 -178.99979</gml:pos>
<gml:pos>73.99999 -178.99979</gml:pos>
...
<gml:pos>64.99997 -178.99979</gml:pos>
<gml:pos>67.61505 -178.99979</gml:pos>
</gml:LinearRing>
I believe your DS_DataSet is by virtue of being within the DS_Series (implying a default namespace of "http://www.isotc211.org/2005/gmd") carrying a namespace.
Try and map that into your namespace dictionary (you can probably first test through a print to see if it's already in there, otherwise add it and refer to the namespace by your new key).
nsmap['some_ns'] = "http://www.isotc211.org/2005/gmd"
len (charts_tree.xpath('//*/some_ns:DS_DataSet',namespaces=nsmap))
Which becomes:
nsmap['gmd'] = nsmap[None]
nsmap.pop(None)
len(charts_tree.xpath('//*/gmd:DS_DataSet',namespaces=nsmap))