Comments (1)
Ok @thoni56, now all the original cross-reference links that were lost during document conversion have been restored.
As mentioned above, I've mainly adopted the cross reference format where the text shown is "Chapter X", "Sec. X.X" or "Appendix X".
But in some places it seemed more appropriate (IMO) to use the Section name in the link text, instead. This being a rather arbitrary choice, I've adopted this alternative approach when it seemed to me that mentioning the actual section title would add meaningful information to the reader — eg, when the referenced section deals with side topics, and providing the full title would allow the reader to associate the context of the reference (keywords or topic), whereas using just a section number would leave the reader clueless about where that extra info mentioned belonged to.
My reasoning is that the reader won't always click on the cross-reference link, but rather carry on with the current topic being studied. So, sometimes a numbered link is more than enough (ie, the reader will have to click to find out more), but at other times using the section title in the link could provide extra meaning to the context.
Of course, changing these links is just a simple issue, nothing irreversible about them — text-based links simply add the reference tile again, after a comma:
<<Some Section>> // xref with sec number
<<Some Section,_Some Section_>> // xref with sec title
So any of this can be changed later on, I just followed my instict on this right now, and saw it as a chance to test the two approaches (which, by the way, can coexist peacefuly side by side, as was already the case in the original document which adopted execeptions too, according to context).
So, cross-references are now out of the way and I can start working on rebuilding the Index!
from alan-docs.
Related Issues (20)
- Switching to the Rouge Highlighter HOT 10
- ALAN Manual Is Not Highlighted
- MANUAL: Fix MESSAGEs
- Describe how nested containers are (not) handled wrt. limits HOT 1
- Post-Rouge Updates
- Add Conversion Guide to Website HOT 2
- HLJS: Missing Alternative ALAN Themes
- Highlight ALAN: Add Block Comments Support HOT 1
- Highlight.js ALAN: Add Block Comments Support
- XSL FOP: Missing Alternative ALAN Themes
- Update document preamble for the manual HOT 6
- Manual: Explain VERB Definitions With Multiple IDs
- ALAN Manual: Update to Beta8 HOT 8
- Mention How the AGAIN Message Is Tied to VISITS HOT 3
- ALAN Manual: Update Swedish List of NOISE WORDS
- ALAN Manual: Add Parts & Make Code Prose-Cased HOT 6
- Sass Themes: Fix Operators Colouring HOT 1
- Revise Ch 5. Running An Adventure
- Spurious Diagram Images in 'published' Branch HOT 1
- Adopt New Official Extensions for ALAN3 Solution and Transcript Files
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from alan-docs.