Writing devices for internal referencing [in LaTeX]

[scrive]

I’ve been writing with Scrivener long enough now (Thank you L&L!) that I’d like to be able to make reference to internal document passages, not unlike the [[Chapter or Section Title]] document links that are a powerful Scrivener tool. Such a tool however, is not quite enough when I’d like to link to a non-[[Chapter or Section Title]] passage. I can always copy-and-paste the appropriate passage instead of referencing the pertinent passage, but that creates a maintenance issue that I’d like to avoid.

I’ve read about the [[document links]] in the Scrivener manual, but I’ve not found anything like the [[Chapter or Section Title]] document link tool to accomplish what I need. I may be completely missing a device or tool to do what I’d like to. My apologies if I am missing such an obvious Scrivener writing device; if not I’d like to hear what devices others are using to accomplish the non-[[Chapter or Section Title]] internal document links I am hoping for.

Thanks for reading…
scrive

[AmberV]

I don’t know if I understand the special distinction you’ve described, of an internal link only being capable of pointing to a formal chapter or section title—though I suppose if your binder outline precisely describes formal headings in the output, that conflation would be appropriate. Otherwise you can link to anything in the binder, it doesn’t have to be something that prints a heading, and you would address it normally by its binder title when typing in the wiki links.

If by this distinction you mean linking to text inside binder items, then this how-to should help.

[scrive]

Hi AmberV,

Thank you. I’ll have a look …

After a cursory glance at the link you sent, I’m not sure it has what I am looking for. For what it is worth, LaTeX doesn’t appear to have a straightforward solution either, but I may be able to conjure up something using LaTeX’s subparagraph feature.

I’ll let you know if I succeed.

Thanks again for all your help!

scrive

[AmberV]

If you mean this as a document construction question rather than asking about how to use links in Scrivener as a writing tool, then that is something else, not really a Scrivener question at all, but a LaTeX question.

As far as I know, linking to a specific paragraph isn’t something that can be done out of the box because that would be very atypical. Usually a cross-reference will need to state what it is referencing (an equation, figure, section number, whatever) and a reader will expect to be taken to an object of some sort, not to the middle of a page with no visual indication of what they are meant to be looking for.

So that explains why there aren’t out of the box tools for doing that, but I’m sure there is some package out there that can make it happen.

[scrive]

Hi AmberV,

As it turns out, there is a solution to my multi-year-long quest for a non-titled-based system of cross-referencing text within a Scrivener-LaTeX document. With the help of the people over at SE, after an appeal for a solution to an MWE I posted, a noted contributor took pity on me and dropped-a-dime on an existing feature: hypertarget, a function that already exists within the hyperref package.

With hypertarget, I am able to use all of my Scrivener writing tools to format and otherwise manage how, when and where I place a hypertarget, along with the hyperref reference to that hypertarget.

With the addition of a small macro, I’m able to specify the page number of the hypertarget wherever I place the corresponding hyperref reference.

There doesn’t appear to be much documentation on hypertarget, and even less support, which may explain why it took we so long to find the hyperref function.

Now I’m off to the races with respect to the many dozens of internal cross references that I can now more accurately and succinctly delineate where I may have force-fit a title-style link to achieve the cross-reference, when in fact all I really needed was a hypertarget.

It may have taken me years to assemble my Scrivener-LaTeX concoction of writing tools, but it’s the little discoveries like hypertarget that are making the overall effort worth it.

Let me know if you or anyone is interested in more detail on how I’ve incorporated the hypertarget function within my Scrivener-LaTeX document.

For what it is worth, I wasn’t looking for a Scrivener-LaTeX solution in my search for cross-referencing text (without using titles) within a Scrivener document. I was actually hoping that I had missed some feature within Scrivener that would provide such a capability. I must admit that I am a little surprised that such a feature is not natively available within Scrivener. But from my research, it would appear such a feature is not at the top of many people’s list whether it be Scrivener or LaTeX.

Thanks for reading, and for all your assistance,
scrive

[AmberV]

@scrive

For what it is worth, I wasn’t looking for a Scrivener-LaTeX solution in my search for cross-referencing text (without using titles) within a Scrivener document. I was actually hoping that I had missed some feature within Scrivener that would provide such a capability. I must admit that I am a little surprised that such a feature is not natively available within Scrivener. But from my research, it would appear such a feature is not at the top of many people’s list whether it be Scrivener or LaTeX.

Well again, I feel there is perhaps a competition between what one might want to do in a writing environment, and what one needs to do in a document that isn’t being addressed. For the latter, I would repeat that in traditional publishing, it is very rare to link to a paragraph in the middle of nowhere. That is an awkward proposition without some kind of visual numbering system (end notes) or caption/titling numbering that the reader can locate with. The mechanism you are referring to here is not suitable because one cannot click on a hyperlink in a paper book. So for that—there is a natural dearth of options because it isn’t a terribly useful thing to do in most works. Obviously there will always be exceptional cases, but exceptions do not generally bring with them a flood of tools and support.

But for writing and note-taking? Well that’s another thing entirely. There it makes all kinds of sense to be able to point to a specific piece of text, perhaps from a list of editing notes, or for some other wide variety of purposes. Whether that is done through a clickable link or some other means is up to the software.

In Scrivener, as noted in the linked thread, there are many ways to easily accomplish these kinds of internal references to self. We don’t use links for that, on account of technical limitations mainly, but methods that are more durable anyway, capable of working in print (visual references you can find by looking for them) and even the simplest of file formats (TXT). The medium is quite similar to how you would create such a reference to self in a paper-based environment, but with a good dose of technology on top to make the hardest parts of that easier. Instead of having to rifled through dozens of pages looking for a numerical marker or whatever in a margin in red ink you just punch a shortcut on a selected marker and get an instant list of them throughout the project that can be jumped straight to immediately.

[scrive]

Hi AmberV,

Thank you for your note. I’m just not sure if my drive for a free-standing cross reference system between what might otherwise appear to be disparate sections of text is due to my attention-deficit inability to reduce the story I am trying to tell into a straightforward, straight-line logical series of topics that follows some natural narrative, or if the topic I have taken on is just so complex that a straight-line narrative does not fit the real-world data.

It may be that my desire to make connections between disparate sections of text is just part of the process of pulling the story together into a straight-line narrative, in which case the disparate connections are a sort of internal editing tool that might help me make full scale reorganizations of the story to create that straight-line narrative that most authors hope for, dream of and work towards.

At this point I honestly have no idea exactly what REAL purpose the disparate connections are serving, particularly since I am so much out of my element with this monstrosity I have created.

For now, I’m acting as if the disparate connections are a valid device for what I would hope is anyone who might be interested in reading the words, and could benefit from the odd disparate connections that I see, and might help to enlighten the reader. Who knows, but for now, it’s the direction I am headed in.

It may not be good form for a writer to make such seemingly disparate connections, given the thousands of years of history written on paper. Or, it may be that with this new electronic medium, there is a new degree of freedom we have as writers to connect the dots, and ooh what a powerful world of word connections that might allow, if done well.

I guess time will tell.

Thanks again for all your help,
scrive

[bernardo_vasconcelos]

@scrive, I am not sure if you are compiling directly to LaTeX. If you are using Pandoc, all you have to do is create a markdown or HTML anchor. I simply add []{#scrivauto:<$linkID>} to all my text sections during the compilation process (as prefix). To link to them, I simply use scrivauto:<$linkID> as the link text pointing to the right text section, as is scrivauto:<$linkID>.

That is how it looks like using markdown.

Or, in TeX:

\hypertarget{header}{%
\section{Header}\label{header}}

\protect\hypertarget{scrivauto:1}{}{} Lorem ipsum dolor sit amet,
consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

\protect\hypertarget{scrivauto:2}{}{} Lorem ipsum dolor sit amet,
consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

\protect\hyperlink{scrivauto:1}{A link to the first paragraph}.

\protect\hyperlink{scrivauto:2}{A link to the second paragraph}.
% If you use \autoref{scrivauto:2}, the page number will be printed, which is what I prefer.

[AmberV]

@scrive

For now, I’m acting as if the disparate connections are a valid device for what I would hope is anyone who might be interested in reading the words, and could benefit from the odd disparate connections that I see, and might help to enlighten the reader. Who knows, but for now, it’s the direction I am headed in.

Well one nice thing about Scrivener is that you don’t have to make up your mind and then live with the consequences, or face dozens of hours of editing to remove links if you change your mind. Since these kinds of things can be generated by the compiler, they can also not be generated.

These are very good tips, @bernardo_vasconcelos. I do believe Scrive is using a highly modified version of our LaTeX project template to compile .tex directly rather than going through a Markdown translation layer, but it’s great to know Pandoc handles this directly.

[nontroppo]

Hi @bernardo_vasconcelos, could you detail how you use the prefix for each paragraph, are you using styles or splitting the documents in to paragraphs in the Binder and using Section Layouts?

EDIT: ah, I realise you are perhaps wring markdown directly in Scrivener?

[scrive]

Hi bernardo_vasconcelos, AmberV, and nontroppo:

To: bernardo_vasconcelos: Thank you for your code. I am compiling directly to a LaTeX .tex file. I’ll have to have a look at your code to see if/how I can incorporate it into my Scrivener code.

To All: Please forgive me if I’ve strayed a bit too far from the traditional Scrivener code. (And feel free AmberV to delete this post if it crosses any red lines for this web site.)

I thought for those few of us who use Scrivener+LaTeX, I’d assemble an MWE (Minimum Working Example) to demonstrate how I use the LaTeX \hypertarget function in the hyperref package to make non-titled links between disparate paragraphs.

Please note that the following MWE should be fully stand-alone, e.g when using a standard LaTeX Typesetting app, it should be Typeset-able, right ‘out-of-the-box’. With my Scrivener+LaTeX setup, I can include any and all of the appropriate parts of the MWE code below directly within my Scrivener .scriv Project file. I can then compile the Scrivener .scriv file into a .tex file using Scrivener, which I then Typeset using the TexShop app into the final PDF file.

Here is the MWE: (apologies if the formatting is a bit difficult to read.)

%____________________ MWE start_____________________

% Note: The following code needs to be Typeset TWICE for the page number in \pageref{} to work properly.

\documentclass{article}
\usepackage{hyperref}
\usepackage[english]{babel}
\usepackage{blindtext}
\usepackage{contour}
\usepackage[normalem]{ulem}
\usepackage{verbatim}

\newcommand*{\myuline}[1]{%
\uline{\phantom{#1}}%
\llap{\contour{white}{#1}}%
}

\makeatletter
\newcommand{\linkdest}[1]{%
\Hy@raisedlink{%
\hypertarget{#1}{}%
}%
\phantomsection%
\label{#1}
}%
\makeatother

\begin{document}
\clearpage

Click here to see the \hyperlink{link:TheLastPara}{The;\textbf{Last};Paragraph} on page \pageref{link:TheLastPara}. \par

\linkdest{link:TheFirstPara}\textbf{The \myuline{first} paragraph of the story}.
\blindtext\par

\linkdest{link:TheSecondPara}\textbf{The \myuline{second} paragraph of the story}.
\blindtext

\newpage

\linkdest{link:TheThirdPara}\textbf{The \myuline{third} paragraph of the story}.
\blindtext

\newpage

\linkdest{link:TheLastPara}\textbf{The \myuline{last} paragraph of the story}.
\blindtext \par

Click here to see the \hyperlink{link:TheFirstPara}{The;\textbf{First};Paragraph} on page \pageref{link:TheFirstPara}. \par

Click here to see the \hyperlink{link:TheSecondPara}{The;\textbf{Second};Paragraph} on page \pageref{link:TheSecondPara}. \par

Click here to see the \hyperlink{link:TheThirdPara}{The;\textbf{Third};Paragraph} on page \pageref{link:TheLastPara}. \par

Click here to see the \hyperlink{link:TheLastPara}{The;\textbf{Last};Paragraph} on page \pageref{link:TheLastPara}. \par

\end{document}

% Note: The following code needs to be Typeset TWICE for the page number in \pageref{} to work properly.

%___________________ MWE end______________________

For the Scrivener+LaTeX’ers here, I’ve adjusted how the \hypertarget function positions the connection to the text using the Hy@raisedlink function. For more info, check out the SE post at: hypertarget seems to aim a line too low for more information.

Let me know if anyone has any questions.

Enjoy!

HTH,
scrive

[bernardo_vasconcelos]

@nontroppo

Hi @bernardo_vasconcelos, could you detail how you use the prefix for each paragraph, are you using styles or splitting the documents in to paragraphs in the Binder and using Section Layouts?

Ian (@nontroppo), apologies; I should have mentioned that this is tied to splitting the paragraphs in the binder. I am pretty sure I learned this approach from the Scrivener Manual template or some other template from @AmberV (maybe yours, even?), but I can’t recall for sure.

It would work very similarly for Markdown or LaTeX, of course. Usually, I make the link show up in the final TeX file as \autoref{scrivauto:ID} for it to becomea page ref, but section number is not bad either.

[scrive]

As a challenge to myself, I was able to adopt the \hypertarget function to two Scrivener Styles to simplify the process of creating such an internal, non-titled link within my Scrivener project, as I write.

I’ve named the Styles I created as HyperTarget Destination (e.g. the target text for the \hypertarget) and HyperTarget Source (e.g. where the \hypertarget originates} in the list of Styles.

Utilizing the above Scrivener Styles, a sample of the HyperTarget Source can look like:

and a sample of the HyperTarget Destination can look like:

With a bit of research, I was able to employ the LaTeX \Hy@raisedlink function to adjust the preview pop-up window to provide a nice view of the HyperTarget Destination, e.g.:

Hopefully, this will facilitate the creation of those \hypertarget connections on the fly as I complete the different sections of text as I write.

Otherwise, those connections tend to evaporate in my mind after I have moved on to other sections of my writing. It would have been nice to have had such a feature from the beginning, but perhaps I’ll be able to remember the many earlier connections I’d forgotten during my rewrites.

Thanks for reading,
scrive

[jpkell]

What is the functionality that enables one to output the exact page of a textual reference upon compile (e.g. “…in a related discussion in Section 2.2 on page 34”)?

[bernardo_vasconcelos]

@jpkell

What is the functionality that enables one to output the exact page of a textual reference upon compile (e.g. “…in a related discussion in Section 2.2 on page 34”)?

\autoref{label}, but this is only useful if you are familiarized with LaTeX.

[scrive]

@jpkell

What is the functionality that enables one to output the exact page of a textual reference upon compile (e.g. “…in a related discussion in Section 2.2 on page 34”)?

Hi jpkell,

Apologies for not responding sooner … sometimes I can get caught up in the re-write …

Are you using Scrivener+LaTeX?

If so, it may take me some time but I can cobble together a few lines of code to respond to your question. If not, would you still be interested in the LaTeX code that provides the functionality for “(e.g. “…in a related discussion in Section 2.2 on page 34”)”.

Thank you for the inquiry,
scrive

[jpkell]

I sometimes use Scrivener+LaTeX, but I mostly use Scrivener+Markdown+Pandoc, with many LaTeX commands being passed through to Pandoc in my Markdown text. Not sure if the functionality would make its way through this process to a final compiled document. And in any case, I’d want this functionality primarily in a book manuscript, whose pages would differ from whatever Pandoc compiled in the first place.

[nontroppo]

Pandoc normally passes latex through — and you can also explicitly mark inline and block elements: Pandoc - Pandoc User’s Guide which will be removed for other format outputs.

[scrive]

Hi jpkell,

I was wondering if anyone might be interested in an internal, non-titled link for Scrivener+LaTeX. I created the two Styles mostly as a way to NOT have to delve back into the code, but to make the feature available as I re-write.

I’m chafing-at-the-bit to implement the feature within my 700+ page document. The problem is I’ve forgotten a lot of the connections I’d thought of making long ago. Now I’m hoping to play catch-up.

The joke is on me as I am now in a position to try and explain what I did to someone else. Upon reviewing my own code, it took me a while to reload the code back into my cerebral cortex. The end result is I’ll need to massage the code a bit before I can try to explain it to someone else.

Too often I just want the code to work, not to make sense to anyone else. My bad!

If you can bear with me, I will try to assemble a package of code to explain the feature. The challenge for me is I don’t quite know at this point how reliant my code is on the hundreds of code snippets and functions that I’ve assembled within my ~25K lines of code.

If you’re like me, such a feature may be worth the wait. My apologies for any delay.

The one question I have is are you looking for two similar Style entries like I discussed in my original posting? Have your yourself created any new Styles in your Scrivener project?

Thanks for the inquiry,
scrive

[jpkell]

Oh it’s no problem at all; I’m in no hurry to implement this—just curious how it might be done within my Scrivener+Markdown+Pandoc → PDF/docx workflow.