[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
- Re: [Taler] (docs) /private/orders,
Christian Grothoff <=