Links to sections of same page in asciidoc - asciidoc

I'm writing some text that will be converted to HTML, as a long single page.
Can't figure out how to make links to sections as in HTML using #some-id, so that a user when clicking it will go up or down the web page to
<h2 id="some-id">Section A</h2>
<p>Lot's of lines</p>
Go to section

What you're referring to is called an "internal cross reference".
The markup for an internal cross reference is:
<<id,caption>>
where id is an element on the page that has an identifier, typically a title, and caption is optional text that should appear in the link.
You can link to titles that have auto-generated ids, but the formation of the ids could vary based on the attributes idprefix and (for Asciidoctor) idseparator. The default is to make the title text lowercase, prefix with an underscore, and replace spaces and other punctuation with underscores. The id for the title "Let's make a game!" would be _lets_make_a_game.
It is often better for you to specify your own id that will remain stable even if you edit the text of a title. You can do so with:
[[id,label]]
where id is the identifier you want to specify, and label is the optional, default label that may be used for the cross reference (if the cross reference itself doesn't specify a caption).
If the element that your cross reference points to is a title, you can omit the caption and the label, and the link will use the title's text as its own text.
For Asciidoc, see: http://asciidoc.org/userguide.html#_internal_cross_references
For Asciidoctor, see: https://asciidoctor.org/docs/user-manual/#internal-cross-references
Usage Example:
This is how we assign an ID:
== Debug Running Pods [[debug_running_pods]]
Refer to an ID:
<<debug_running_pods>>

Another option is to use the link: macro. Here's an example from one of my Asciidoctor docs:
link:#_explore_the_public_directory[17.4. Explore the `public` directory]
Info about this is in https://asciidoctor.org/docs/user-manual/#url. Here's an excerpt from the relevant part:
When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the link macro.

Related

Are there cases of editing HTML output by Aspose.Word with CKEditor?

I am in trouble with the event that the sentence edited in CKEditor are not output to Word as a result of inheriting attributes of “-aw-import:ignore”.
A tag with this attribute is a tag that conveys the attribute of the original word when converting from html to word, and it is not output as word as a meta tag.
If the sentence entered in CKEditor inherits the attributes, it will not be output as word by mistake.
Aspose.Words writes this "-aw-import:ignore" only when it needs to make certain elements visible in HTML that would otherwise be collapsed and hidden by web browsers e.g. empty paragraphs, space sequences, etc.
Currently we mark only the following elements with “-aw-import:ignore”:
Sequences of spaces and non-breaking spaces that are used to simulate
padding on native list item (<li>) elements.
Non-breaking spaces that are used to prevent empty paragraphs from collapsing.
However, note that this list is not fixed and we may add more cases to it in the future.
Also, please note that Aspose.Words write   instead of because is not defined in XML. And by default Aspose.Words generate XHTML documents (i.e. HTML documents that comply with XML rules).
I work with Aspose as Developer Evangelist.
Please find below list of custom styles that Aspose.Words uses to save extra information in output HTML and usually this information is used for Aspose.Words-HTML-Aspose.Words round-trip. We will add description of these entities in documentation as soon as possible.
-aw-comment-author
-aw-comment-datetime
-aw-comment-initial
-aw-comment-start
-aw-comment-end
-aw-footnote-type
-aw-footnote-numberstyle
-aw-footnote-startnumber
-aw-footnote-isauto
-aw-headerfooter-type
-aw-bookmark-start
-aw-bookmark-end
-aw-different-first-page
-aw-tabstop-align
-aw-tabstop-pos
-aw-tabstop-leader
-aw-field-code
-aw-wrap-type
-aw-left-pos
-aw-top-pos
-aw-rel-hpos
-aw-rel-vpos
-aw-revision-author
-aw-revision-datetime

Create a link with independent text

Is it possible to create an intra-document link with sphinx, such that the displayed text is independent of the link and destination?
Currently, I make intra-document links like so:
.. _Label_For_Section:
===============
Name Of Section
===============
The link :ref:`Label_For_Section` is rendered as "Name Of Section".
The link Label_For_Section_ is rendered as "Label_For_Section".
What I want is a way to have a link, where the destination text, link label, and displayed link text can all be different strings. Eg a link to a section called "A" with a label .. _B: which is rendered as "C"
Note
I noticed that other kinds of links (eg external hyperlinks) are similarly constrained, and I figure the solutions may look similar, however I am looking specifically for a solution for intra-document links.
See Cross-referencing arbitrary locations, specifically the ref role.
:ref:`Link title <label-name>`

Can't use :ref: with a Label using Sphinx doc

I have a problem with using Sphinx-doc's :ref: role, I put a label above a paragraph and then I try to link to that label from another doc but inside the same project.
The label I use in one document:
.. _hal_1k_1p:
And the ref I try to use to link to that label:
:ref:`Link title hal_1k_1p`
But I only get this error message when building the doc:
WARNING: undefined label: link title hal_1k_1p (if the link has no
caption the label must precede a section header)
What am I doing wrong?
Okay, looking at :ref: you need to have this:
:ref:`Link title <ha1_1k_1p>`
to link to that label.
Ensure you have angle brackets surrounding your label like so: <label>
First make sure that your ref is in the format:
Label:
.. _yourlabel:
Reference:
This is a reference to :ref:`yourlabel`.
or (if you want to give it a custom name)
This is a reference to :ref:`my very own label <yourlabel>`.
The label definition contains the leading underscore (_) while the reference doesn't! Also make sure that you didn't accidentally copy the colons from the label definition (:) to the reference.
If that doesn't help try switching languages back to english temporarily in your conf.py:
language = 'en'
If you see that this works you can switch back. Somehow this solved my problem. Maybe related to: https://github.com/sphinx-doc/sphinx/issues/1300

How to setup Table of Content in TiddlyWiki

If I go TiddlyWiki site I can see tab Content. How can I create my own table of content for my tiddlywiki file?
I found the documentation for this really confusing, but here's what I did that works best:
<div class="tc-table-of-contents">
<<toc-selective-expandable 'TableOfContents' sort[ind]>>
</div>
Then, tag each tiddler with TableofContents.
Lastly, when editing each tiddler, add a new field named "ind" (for index - you can change this to whatever you like, so long as it's not being used elsewhere, of course). Assign a value to "ind" starting with 0 to tell it what order you want the tiddlers to go in. I incremented by 10 instead of 1 in case I want to rearrange a few things or insert more in the middle.
Create a new tiddler and give the title Contents
Under tags, give the value $:/tags/SideBar
Under type the text for this tiddler, give
<$list filter={{$:/core/Filters/AllTiddlers!!filter}} template="$:/core/ui/ListItemTemplate"/>
This is explained in the documentation.
The short version: Add some tag (e.g. Content) to the pages you want to appear in the TOC; then in the place where you want it to appear, use one of the macros with that tag name (e.g. <<toc Content>>). To make a nested TOC, tag pages with the names of tags that appeared at the top level. So for example if you have a tiddler named First that is tagged with Content, then you can tag more tiddlers with First, and they will appear indented below First in the TOC.

How can I query XPath matching an attribute from one tag against another attribute from another tag?

I'm scripting a web app that has labels for input fields. EG:
<label for="surname">Family Name:</label>...<input id="surname" ...></input>
I'd like to be able to write an XPath expression that takes the text "Family Name:" to match the label, then takes the "for" attribute from the label and uses that to find the associated input tag by matching its "id" tag.
I can make this "work" as follows:
//label[contains(.,"Family Name:")]/following::input[1]
However, for this web app I think it would be more reliable to match for/id. (EG: How can I be sure that in all possible layouts the first input tag following the label is the one I want? And what happens if somewhere down the line this page is rendered using a right-to-left script?
My ultimate aim is to create a library function that we can use to write QA scripts in advance of web pages to test against, when all we have is a picture or document with an input field labelled "Family Name:" and no idea what id some programmer will ultimately assign to the field.
Maybe this is what you're looking for?
//input[#id = //label[contains(., "Family Name:")]/#for]
As for your ultimate goal, you may want to take a look at the XPath gem for Ruby. Some of what you're doing may already be implemented there. (Specifically, check out the library's HTML Helpers)

Resources