In reStructuredText, how does one do an 'inline' include of an external document fragment? - restructuredtext

I have a bullet lists of hyperlinks to articles, where each article has a one-line summary. And, I would like my one-line summary to appear in the bullet list:
Thing1: This is a thing.
Thing2: This is also a thing.
Because (1) my summaries quite involved, (2) I have many articles, and (3) even more bullets, I'd like to put the summaries into their own document fragments and 'include' them in both the bullet list and the article. But, this does not fly in reStructuredText:
* `Thing1`_: .. include:: summary-of-thing1.txt
* `Thing1`_: .. include:: summary-of-thing2.txt
The text .. include:: summary-of-thing1.txt ends up in my generated HTML document, and this appears to be because directives (like .. include::) must be in their own 'paragraph' like this:
* `Thing1`_:
.. include: summary-of-thing1.txt
But, doing that puts my document fragment into its own paragraph, which makes it look like this:
Thing1:
This is a thing.
Thing2
This is also a thing.
When, what I really want is for my summaries to appear on the very same line as my hyperlinks.


OK, I see this is what .. replace:: is for. One can say this:
* `Thing1`_: |summary-of-thing1|
* `Thing2`_: |summary-of-thing2|
.. include:: summaries.txt
And put the summaries into summaries.txt like this:
.. |summary-of-thing1| replace:: This is a thing.
.. |summary-of-thing2| replace:: This is also a thing.

Related

Hyperlinks with ReStructured Text

I would like to write reusable hyperlinks the same way I do with Markdown:
You can also follow [this link][1] if you want. But if you really don't
want to follow [my link][1], you could try [a better one][1].
[1]: http://google.com
Is there a way to do this with ReST? When I try to convert the above code with Pandoc I get 3 times the same link:
You can also follow `this link`_ if you want. But if you really don’t
want to follow `my link`_, you could try `a better one`_.
.. _this link: http://google.com
.. _my link: http://google.com
.. _a better one: http://google.com

You can use an embedded alias to replicate this functionality
You can also follow `this link <1_>`_ if you want. But if you really don't
want to follow `my link <1_>`_, you could try `a better one <1_>`_.
.. _1: http://google.com
see this great blog post for more hyperlink examples.

Duplicate substitution definition name with only::

I'm using Sphinx to build our end user manuals, consisting of many long tables. Special table cells should be highlighted with a color. I derived a solution working for HTML and likewise for LaTeX.
Now I wanted to combine both solution into the rst-files, by using the only directive.
.. only:: html
.. |bS| raw:: html
<div style="color:blue;">
.. |bE| raw:: html
</div>
.. only:: latex
.. |bS| raw:: latex
\cellcolor{blue}
.. |bE| raw:: latex
\empty{}
Sphinx-build now issues the errors:
WARNING: Duplicate substitution definition name: "bS".
WARNING: Duplicate substitution definition name: "bE".
And I have \cellcolor{blue} in my HTML Output, which isn't supposed to happen.
What I'm doing wrong here?

Notepad++ FunctionList

ok .. I have an odd "followup" to this question:
Notepad++ Function list for SQL
Got my answer there ... and this question is a bit different .. so I figured it's better as seperate question. :)
So to recap: after a couple minor tweaks to the regexp provided by Chris (Thx!!) I managed to get it to pull the Package name (as well as optional BODY keyword .. so I know if it's header/body if both are in same script ) ..
Final parser is this:
<parser id="plsql_func"
displayName="PL/SQL"
commentExpr="((/\*.*?\*)/|(--.*?$))">
<function
mainExpr="^[\w\s]{0,}(PACKAGE|FUNCTION|PROCEDURE)[\s]{1,}(BODY){0,1}[\s]{0,}[\w_.]{1,}">
<functionName>
<nameExpr expr="^[\w\s]{0,}(PACKAGE|FUNCTION|PROCEDURE)[\s]{1,}\K(BODY){0,1}[\s]{0,}[\w_.]{1,}"/>
</functionName>
</function>
</parser>
That works great .. however, results in something that looks like this:
Now for the tricky part (I'm fully expecting a response of "not possible" :) but figured it can't hurt to ask :) )
Is there any way to get that tree view expand/collapse option which is currently only on pk_test.sql ... have that on my pkg header/body records .. so like this:
I'm guessing that's asking for too much? :)
(would be nice though .. hehe)

Notepad++ Function list for SQL

quick question .. I'm trying to get the function list option in Notepad++ going ...
Now, I found this thread:
Notepad++ Function List for PL/SQL
which helped get me started, however, I'm still struggling with something, and I can't seem to wrap my monkey-brain around it.
It'll be this section I need to focus:
<function
mainExpr="^[\t ]*(FUNCTION|PROCEDURE)[\s]*[\w]*[\s]*(\(|IS|AS)*"
displayMode="$functionName">
<functionName>
<nameExpr expr="[\w]+[\s]*(\(|IS|AS)"/>
</functionName>
</function>
That works perfectly fine .. so far.
However, I would like to also see PACKAGE header and PACKAGE BODY names in there as well .. just to help tidy things up.
I figured it'd be easy to tweak the RegExp, however, nothing I've tried is working
So I'm trying to pick out these kinds of scenarios:
CREATE PACKAGE aaa
CREATE OR REPLACE PACKAGE bbb
CREATE PACKAGE BODY ccc
CREATE OR REPLACE PACKAGE BODY ddd
all 4: aaa, bbb, ccc, and ddd.
I can't even get it to pull back one yet.. :(
Hoping I could get some help/hints/something ..
I know this is the main "logic":
mainExpr="^[\t ]*(FUNCTION|PROCEDURE)[\s]*[\w]*[\s]*(\(|IS|AS)*"
that finds the line(s) ..
And trying to matchup the logic with what it finds for .. say, FUNCTIONs, and what I want for PACKAGE ... I tried this:
mainExpr="^[\t ]*(FUNCTION|PROCEDURE|CREATE OR REPLACE PACKAGE)[\s]*[\w]*[\s]*(\(|IS|AS)*"
but even that doesn't pick out the header! O.o
I'm sure there's something I need to do with the part .. but again, not really understanding how it works ??
I've read this :
https://notepad-plus-plus.org/features/function-list.html
but there's obviously something about the syntax/usage of this thing I'm not fully understanding ..
hoping somebody can help me out?

I think your problem is coming from the Regex rather than anything you're doing incorrectly. I've made a new parser based on the one I found here: http://www.hermanmol.nl/?p=240
<parser id="plsql_func" displayName="PL/SQL" commentExpr="((/\*.*?\*)/|(--.*?$))">
<function
mainExpr="^[\w\s]{0,}(PACKAGE BODY|PACKAGE|FUNCTION|PROCEDURE)[\s]{1,}[\w_]{1,}">
<functionName>
<nameExpr expr="^[\w\s]{0,}(PACKAGE BODY|PACKAGE|FUNCTION|PROCEDURE)[\s]{1,}\K[\w_]{1,}"/>
</functionName>
</function>
</parser>
For me this seems to correctly pull out the Package, Procedures and Functions.
One thing to note however, I could not get this to work using a file extension assocation, and used the following instead to test on a text file: <association langID= "0" id="plsql_func" />
I also placed the updated functionList.xml file in both the Program Files (x86)\Notepad++ and the Users\xxxxx\AppData\Roaming\Notepad++ directories.
Edit - a short explanation of the Regex, I'm not great at Regex but it was requested in the comments
^[\w\s]{0,} - From the beginning of the line, find 0 or more letters or white space characters
(PACKAGE BODY|PACKAGE|FUNCTION|PROCEDURE) - followed by any of these
[\s]{1,}[\w_]{1,} - followed by one or more spaces, followed by one or more words

Thanks Chrisrs2292,
I was helped by the location of the functionList.xml file in Users\xxxxx\AppData\Roaming\Notepad++ directories.
RegEX for T-SQL:
<association id= "T-SQL_func" langID="17"/>
<!-- T-SQL-->
<parser displayName="T-SQL" id="T-SQL_func" commentExpr="(?s:/\*.*?\*/)|(?m-s:--.*?$)">
<function mainExpr='(?im)^\h*(create|alter)\s+(function|procedure)\s+((\[|")?[\w_]+(\]|")?\.?)?((\[|")?[\w_]+(\]|")?)?'
displayMode="$functionName">
<functionName>
<nameExpr expr='(?im)(function|procedure)\s+((\[|")?[\w_]+(\]|")?\.?)?((\[|")?[\w_]+(\]|")?)?' />
</functionName>
</function>

Working from what Chrisrs2292 has provided from above, I played around with some PL/SQL code on regex101.com to find a regular expression to find the functions/procedures/etc, and got put that into the functionList.xml.
<parser
displayName="SQL Node"
id="sql_node"
commentExpr="((/\*.*?\*)/|(--.**$))"
>
<function
mainExpr="^[\w\s]+(PACKAGE BODY|PACKAGE|PROCEDURE|FUNCTION)\s+[\w"\.]+"
>
<functionName>
<nameExpr expr="^[\w\s]+(PACKAGE BODY|PACKAGE|PROCEDURE|FUNCTION)\s+\K[\w"\.]+"/>
</functionName>
</function>
</parser>
The big change was I had include the double quotes (using the XML code of ") and dot (the \.) since many times I use the quotes and like to use the fully qualified name (schema.procedure|function|etc). Minor changes are replacing the {0,} with * and {1,} with +. These are minor, cosmetic changes are should be interchangeable.

Writing several texts which follows same link with reST

the following reST don't work as expected. How can I do it right?
Only the word python_ in this text is linked. What to do if
I want using other words such as `like it <python_>`_ to jump
to the same link?
.. _python: http://www.python.org
Thanks for any help!
mutetella

This isn't a really well documented as far as I have been able to read but the OP's method should work. I've tested the following input with rst2html.py (v 0.11) and Sphinx (v 1.2b1) on cygwin. Both generate the correct hyperlinks to the CNN site.
* According to `CNN <http://www.cnn.com/>`_ the economy...
* According to `The Amazing Cable News Network`_ the economy...
* According to the `Cable News Network <CNN_>`_ the economy...
.. _The Amazing Cable News Network: CNN_
.. CNN: http://www.cnn.com/
The second form was suggested by #Ajay, although it seems odd to me to have to create another alias to get the text you want, but the third form seems to be what the OP was looking for and as far as I can tell it works fine. The third form also works for internal links within the document.

Resources