Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-wg] Reasons to not use Asciidoc as a foundation for a software documentation language -- experiences from the N4JS project

On Mon, Feb 17, 2020 at 12:32 PM Manfred Moser <manfred@xxxxxxxxxxxxxxxx> wrote:
 
I tend to do the same.. an anchor imho needs to be able to stay the same even if the exact wording of the title or whatever changes. In my experience this happens all the time and you want to ensure that any deep links from outside the docs continue to work .. 


To be fair, this has little to do with AsciiDoc and is primarily an information architecture problem. The same exact problem exists in DocBook. Either you specify an explicit ID so it's stable or you rely on one auto-generated from the content, which can change if that content changes.

If we can think of a way to shorten the explicit IDs (such as through inheritance), we could certainly consider it as a language improvement. Until then, the solution (also true in DocBook) is to shorten the IDs. So instead of:

[[sec:_No_line_terminator_allowed_here__handling]]

You'd type:

[#s_handle-no-line-term]

This is not the thread to be discussing a solution. I'm merely pointing out that it's something the spec project could take up. As stated in the welcome posts, we have lots of such requests and this working group gives us the structure to address them. If AsciiDoc were perfect, we wouldn't be here discussing how to improve it.

Best Regards,

-Dan

--
Dan Allen, Vice President | OpenDevise Inc.
Content ∙ Strategy ∙ Community
opendevise.com

Back to the top