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

Dan Allen wrote on 2020-02-17 12:41 (GMT -08:00):
> 
> 
> On Mon, Feb 17, 2020 at 12:32 PM Manfred Moser <manfred@xxxxxxxxxxxxxxxx
> <mailto: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.
> 
> 

I agree with you Dan .. it is not a asciidoc specific problem, but a problem an asciidoc user will regularly have to solve.

Therefore if we can provide a good solution in asciidoc that would be good and one more reason to use asciidoc over other choices ;-) 

Manfred


Back to the top