xrefs and AsciiBinder

[Brian Exelbierd]

By chance I had a conversation yesterday in person with pbokoc, pkovar
and rkratky.  We wound up discussing xrefs (because we are that kind of
cool!).

As you may know, xrefs allow you to link to a piece of content without
having to know where it actually lives.  In DocBook you link to the id
of the section/etc.

AsciiBinder does not support xrefs today.  AsciiDoc has syntax for them,
but the processing that AsciiBinder does to build the site precludes us
from using it.

I believe I can get us something like this working though.  Is there an
interest?

= Xrefs in AsciiBinder

A plugin will be written (I have a rough Proof Of Concept done) that
overloads the AsciiDoc xref syntax.  We would now be able to do the
following:

xref:title_with_underscores_case_insensitive[optional text to use for
the link text - otherwise the title is used]

This would link to the page that has that title.

But what about collisions?  If two pages have the same title, you will
need to be more specific.  Using the Dir entries from the _topic_map.yml
you would specify:

xref:dir/title_with_underscores_case_insensitive[optional text to use
for the link text - otherwise the title is used]

This may or may not work fully if you have a / (slash) in your title. 
If we want xrefs back, I am willing to sacrifice this :) are you?

= Cross-repo linking

As a bonus, we can probably get something like this to work:

xref:content-set@dir/title_with_underscores[optional link text]

The content-set level linking would only be available to books/content
that is jointly published.  The content-set is the same as the name of
the repository.

This means that you could link to the install-guide from the
release-notes but you can't link to the council docs.  The install-guide
and release-notes are published in the same area of the site.  Council
docs is separate.

What do you think?

regards,

bex

[Jean-Baptiste Holcroft]

Le 23/11/2017 à 14:32, Brian Exelbierd a écrit :
>  What do you think? 
If the link uses titles, which are
translatable, it may lead to document 
breakage for localized content.

-- 
Jean-Baptiste Holcroft

[Shaun McCance]

On Mon, 2017-11-27 at 15:45 +0100, Jean-Baptiste Holcroft wrote:
>  Le 23/11/2017 à 14:32, Brian Exelbierd a écrit :
>  > What do you think?
>  
>  If the link uses titles, which are translatable, it may lead to
>  document 
>  breakage for localized content. 
Shouldn't we use the block IDs above the headers? Example:

  [[ch-Working_with_Kernel_Modules]]
  = Working with Kernel Modules

  Go read xref:ch-Working_with_Kernel_Modules.

We can leave this ID stable even when the title is translated. This
could also get rid of the problem of slashes in titles. We could just
decide that we don't put the slash in the ID even if it's in the title.

  [[Doing_Stuff_with_IO]]
  = Doing Stuff with I/O

--
Shaun

[Brian Exelbierd]

On Mon, Nov 27, 2017, at 04:55 PM, Shaun McCance wrote:
>  On Mon, 2017-11-27 at 15:45 +0100, Jean-Baptiste Holcroft wrote:
>  > Le 23/11/2017 à 14:32, Brian Exelbierd a écrit :
>  > > What do you think?
>  > 
>  > If the link uses titles, which are translatable, it may lead to
>  > document 
>  > breakage for localized content.
>  
>  Shouldn't we use the block IDs above the headers? Example: 
This would be ideal.  This was the initial goal.  The question this
becomes then is do we wait on the larger code patch required to
implement this or do we start with titles?

regards,

bex

> 
>   [[ch-Working_with_Kernel_Modules]]
>   = Working with Kernel Modules
> 
>   Go read xref:ch-Working_with_Kernel_Modules.
> 
> We can leave this ID stable even when the title is translated. This
> could also get rid of the problem of slashes in titles. We could just
> decide that we don't put the slash in the ID even if it's in the title.
> 
>   [[Doing_Stuff_with_IO]]
>   = Doing Stuff with I/O
> 
> --
> Shaun
> _______________________________________________
> docs mailing list -- docs(a)lists.fedoraproject.org
> To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org

[Brian Exelbierd]

On Mon, Nov 27, 2017, at 03:45 PM, Jean-Baptiste Holcroft wrote:
>  Le 23/11/2017 à 14:32, Brian Exelbierd a écrit :
>  > What do you think?
>  If the link uses titles, which are translatable, it may lead to document 
>  breakage for localized content. 
I believe we can work around this when the localization is applied.

regards,

bex

> 
> -- 
> Jean-Baptiste Holcroft
> _______________________________________________
> docs mailing list -- docs(a)lists.fedoraproject.org
> To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org