taler
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Taler] (docs) /private/orders


From: Christian Grothoff
Subject: Re: [Taler] (docs) /private/orders
Date: Wed, 1 Dec 2021 20:19:12 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.12.0

On 11/30/21 7:50 AM, Thien-Thi Nguyen wrote:
> 
> () Christian Grothoff <grothoff@gnunet.org>
> () Mon, 29 Nov 2021 09:37:20 +0100
> 
>    Maybe having multiple lines for the choices would be better
>    for Sphinx (see around line 968). We could indeed even go
>    further and spell out all variants:
> 
>    .. http:patch:: /management/instances/$INSTANCE
>    .. http:patch:: /instances/$INSTANCE/private
>    .. http:patch:: /private
> 
>    Would that fix the Sphinx link resolution?
> 
> I think it would.  I have pushed temporary branch ‘dev/ttn’ w/
> a small change to see how people feel about it:
> 
>  https://git.taler.net/docs.git/log/?h=dev/ttn
>  https://git.taler.net/docs.git/commit/?h=dev/ttn&id=ed14d4ab46
> 
> Also, attached are a couple screenshots from my system:
> 
> 
> 
> This was the minimal change needed for taler-nfc-guide.rst to
> compile cleanly (w/o warnings).  It's not future proof.
> 
> IMHO, the result is less pleasing to the eye than the original,
> and could be confusing, as well.  There is also the discrepency
> between including and excluding the trailing ‘$ORDER_ID’.  To
> "properly" accomodate all the possibilities would be to succumb
> to a combinatorial explosion -- not a good strategy for display
> (readability) or maintenance.

I don't think we really have to worry about a combinatorial explosion
here, AFAIK we only have 1-3 cases at most. Maybe 4 if I am mistaken,
but still not enough to really worry about listing them all IMO.

> So, overall, i think the best thing to do is to teach Sphinx
> about optionality somehow (or help others do so), and live w/
> the warnings, however irksome they may be, for now.

Nah, ignoring warnings is bad, they tend to grow. And I'd also not want
to wait on a Sphinx update. For me, your minimal changes and the
screenshot look good enough.

-Christian



reply via email to

[Prev in Thread] Current Thread [Next in Thread]