Skip to content

smart quotes breaks API reference #32

Closed
Closed
smart quotes breaks API reference#32

Description

@methane
methane
opened on Oct 6, 2017

Ref: python-doc-ja/python-doc-ja#771

When Japanese quotes (e.g. 『, 「) are suitable, we use them in translation.
So we don't want to translate English quotes (", ') to Japanese quotes automatically.

Would you disable smart-quotes option in docutils.conf?

Activity

  1. JulienPalard commented on Oct 9, 2017

    @JulienPalard
    JulienPalard
    on Oct 9, 2017
    Member

    Looks fixed by #33

  2. JulienPalard commented on Oct 11, 2017

    @JulienPalard
    JulienPalard
    on Oct 11, 2017
    Member

    Fixed (I just upgraded sphinx to the latest version, they fixed it).

  3. JulienPalard
    closed this as completedon Oct 11, 2017

  4. methane commented on Oct 15, 2017

    @methane
    methane
    on Oct 15, 2017
    MemberAuthor

    @JulienPalard In Japanese, we want use " and ' not only API manual, but also normal paragraph. For example,

    バグ報告フォームには幾つかのフィールドがあります。"Title" フィールドには、問題の説明を 非常に 簡潔に書いてください。

    Could you consider again disabling smart quotes?

    python-doc-ja/python-doc-ja#774 (comment)

    As @cocoatomo said, we can disable it by putting docutils.conf file like below on top of the sphinx project root directory.

    [restructuredtext parser]
smart_quotes:no
  5. JulienPalard
    reopened this on Oct 15, 2017

  6. methane commented on Oct 15, 2017

    @methane
    methane
    on Oct 15, 2017
    MemberAuthor

    python-doc-ja/python-doc-ja#774 (comment)

    @cocoatomo suggests this configuration for docutils.conf:

    [restructuredtext parser]
smartquotes_locales: ja: ""''

    With this config, "title" is used for Japanese and «title» is used for French.

  7. JulienPalard commented on Oct 15, 2017

    @JulienPalard
    JulienPalard
    on Oct 15, 2017
    Member

    That's nice, so we can commit the file in cpython if this is the case, I'm trying it right now.

  8. JulienPalard commented on Oct 15, 2017

    @JulienPalard
    JulienPalard
    on Oct 15, 2017
    Member

    I tried it and got the following results:

    No diff for en and fr as expected, and a diff for japanese as following:
    Lots of:

    < zip application format uses this ability to prepend a standard POSIX 「shebang」
---
> zip application format uses this ability to prepend a standard POSIX &quot;shebang&quot;

    and

    < <em>mainfn</em> 引数は 「pkg.mod:fn」 の形式で指定します。
< 「pkg.mod」 の場所はアーカイブ内の package/module です。
< 「fn」 は指定した module から呼出すことのできる関数です。
---
> <em>mainfn</em> 引数は &quot;pkg.mod:fn&quot; の形式で指定します。
> &quot;pkg.mod&quot; の場所はアーカイブ内の package/module です。
> &quot;fn&quot; は指定した module から呼出すことのできる関数です。

    I'm opening an issue on b.p.o and a PR.

  9. JulienPalard commented on Oct 15, 2017

    @JulienPalard
    JulienPalard
    on Oct 15, 2017
    Member

    Opened the PR: python/cpython#4006

  10. JulienPalard commented on Mar 11, 2018

    @JulienPalard
    JulienPalard
    on Mar 11, 2018
    Member

    python/cpython#4006 has been merged.

  11. JulienPalard
    closed this as completedon Mar 11, 2018

  12. cocoatomo commented on Mar 19, 2018

    @cocoatomo
    cocoatomo
    on Mar 19, 2018

    Same issue is now occurring on Japanese translation on docs.python.org.

    バグ報告フォームには幾つかのフィールドがあります。」Title」 フィールドには、問題の説明を 非常に 簡潔に書いてください。
    https://docs.python.org/ja/3/bugs.html

    docutils.conf does exist on https://github.com/python/cpython/blob/master/Doc/docutils.conf,
    but it does not seem effective.

    I would like to reopen this issue.

  13. cocoatomo commented on Mar 22, 2018

    @cocoatomo
    cocoatomo
    on Mar 22, 2018

    @JulienPalard Would you like to check the comment above?

  14. JulienPalard
    reopened this on Mar 23, 2018

  15. JulienPalard commented on Mar 23, 2018

    @JulienPalard
    JulienPalard
    on Mar 23, 2018
    Member

    Hi @cocoatomo, I tried disabling smartquotes completly, on bugs.html diffs are:

    < 『docs&#64;』 はボランティアによって運営されているメーリングリストです。
---
> 'docs&#64;' はボランティアによって運営されているメーリングリストです。
113,116c113,116
< <p>問題がまだバグトラッカーに登録されていない場合は、Python Bug Tracker のトップページに戻ってログインしてください。まだトラッカーのアカウントをもっていない場合は、サイドバーの 「Register」 リンクを選んでください。また、OpenID を使っている場合はサイドバーの OpenID プロバイダのロゴをクリックしてください。匿名での問題報告はできません。</p>
< <p>ログインできたら、バグを登録できます。サイドバーの 「Create New」 リンクからバグ報告フォームを開きます。</p>
< <p>バグ報告フォームには幾つかのフィールドがあります。」Title」 フィールドには、問題の説明を <em>非常に</em> 簡潔に書いてください。10語以下くらいが目安です。」Type」 フィールドでは、問題の種類を選択してください。バグに関係する 「Component」 と 「Versions」 も選択してください。</p>
< <p>「Comment」 フィールドで、あなたが期待した結果と実際の結果も含め、問題の詳細を説明してください。拡張モジュールが関与しているかどうかと、使用しているハードウェアとソフトウェアプラットフォームも (必要に応じてバージョン情報も) 必ず報告に含めてください。</p>
---
> <p>問題がまだバグトラッカーに登録されていない場合は、Python Bug Tracker のトップページに戻ってログインしてください。まだトラッカーのアカウントをもっていない場合は、サイドバーの &quot;Register&quot; リンクを選んでください。また、OpenID を使っている場合はサイドバーの OpenID プロバイダのロゴをクリックしてください。匿名での問題報告はできません。</p>
> <p>ログインできたら、バグを登録できます。サイドバーの &quot;Create New&quot; リンクからバグ報告フォームを開きます。</p>
> <p>バグ報告フォームには幾つかのフィールドがあります。&quot;Title&quot; フィールドには、問題の説明を <em>非常に</em> 簡潔に書いてください。10語以下くらいが目安です。&quot;Type&quot; フィールドでは、問題の種類を選択してください。バグに関係する &quot;Component&quot; と &quot;Versions&quot; も選択してください。</p>
> <p>&quot;Comment&quot; フィールドで、あなたが期待した結果と実際の結果も含め、問題の詳細を説明してください。拡張モジュールが関与しているかどうかと、使用しているハードウェアとソフトウェアプラットフォームも (必要に応じてバージョン情報も) 必ず報告に含めてください。</p>
130c130
< <p>見つけたバグの報告だけでなく、修正パッチの提出も歓迎します。<a class="reference external" href="https://devguide.python.org/">Python Developer’s Guide</a> には Python へのパッチの始め方について詳しい情報があります。疑問があれば、<a class="reference external" href="https://mail.python.org/mailman/listinfo/core-mentorship/">core-mentorship mailing list</a> は Python の問題解決の過程に関するありとあらゆる疑問への答えを得ることが出来るフレンドリーな場所です。</p>
---
> <p>見つけたバグの報告だけでなく、修正パッチの提出も歓迎します。<a class="reference external" href="https://devguide.python.org/">Python Developer's Guide</a> には Python へのパッチの始め方について詳しい情報があります。疑問があれば、<a class="reference external" href="https://mail.python.org/mailman/listinfo/core-mentorship/">core-mentorship mailing list</a> は Python の問題解決の過程に関するありとあらゆる疑問への答えを得ることが出来るフレンドリーな場所です。</p>

    (Last one diff on the simple quote of "Developer's" from U+2019 to U+0027.)

    How does it looks to you?

    Sadly it diff a lot on english and french version too (U+2019, U+201C, U+201D, ...).

  16. cocoatomo commented on Mar 24, 2018

    @cocoatomo
    cocoatomo
    on Mar 24, 2018

    That result looks good, but disabling smartquotes has bad effect on French version, which is quite undesirable for me.

    So, I suggest to use configuration smartquotes_excludes in conf.py.
    This configuration is more straightforward and flexible than smartquotes-locales in docutils.conf.

  17. JulienPalard commented on Mar 24, 2018

    @JulienPalard
    JulienPalard
    on Mar 24, 2018
    Member

    So, upgrading to sphinx 1.6.6 should do it. I'm trying a local build with 1.7.2.

  18. cocoatomo commented on Apr 17, 2018

    @cocoatomo
    cocoatomo
    on Apr 17, 2018

    Since this commit bumps Sphinx version to 1.7.2, smartquotes was disabledfor Japanese HTML builds and will not break Japanese HTML documents.
    Of course, smartquotes is still enabled for other language.

    Finally, this issue seems resolved with the better way.

  19. JulienPalard commented on Apr 22, 2018

    @JulienPalard
    JulienPalard
    on Apr 22, 2018
    Member

    Nice to hear :)

  20. JulienPalard
    closed this as completedon Apr 22, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions