Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1506077 > unrolled thread

[PATCH 00/12] Fix and update HOWTO Korean translation

Started bySeongJae Park <sj38.park@gmail.com>
First post2016-10-21 17:30 +0200
Last post2016-10-22 03:50 +0200
Articles 12 — 3 participants

Back to article view | Back to linux.kernel

Contents

  [PATCH 00/12] Fix and update HOWTO Korean translation SeongJae Park <sj38.park@gmail.com> - 2016-10-21 17:30 +0200
    [PATCH 07/12] ko_KR/HOWTO: Update information about generating documentation SeongJae Park <sj38.park@gmail.com> - 2016-10-21 17:30 +0200
    [PATCH 10/12] ko_KR/HOWTO: Clean up bare :: lines SeongJae Park <sj38.park@gmail.com> - 2016-10-21 17:30 +0200
    [PATCH 11/12] ko_KR/HOWTO: Add whitespace between URL and text SeongJae Park <sj38.park@gmail.com> - 2016-10-21 17:30 +0200
    [PATCH 03/12] ko_KR/HOWTO: Fix subtitles style SeongJae Park <sj38.park@gmail.com> - 2016-10-21 17:30 +0200
    [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format SeongJae Park <sj38.park@gmail.com> - 2016-10-21 17:30 +0200
      Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst  format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-21 17:50 +0200
        Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format SeongJae Park <sj38.park@gmail.com> - 2016-10-21 18:50 +0200
          Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst  format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-21 19:30 +0200
            Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format SeongJae Park <sj38.park@gmail.com> - 2016-10-21 20:00 +0200
    Re: [PATCH 00/12] Fix and update HOWTO Korean translation Jonathan Corbet <corbet@lwn.net> - 2016-10-21 22:50 +0200
      Re: [PATCH 00/12] Fix and update HOWTO Korean translation SeongJae Park <sj38.park@gmail.com> - 2016-10-22 03:50 +0200

#1506077 — [PATCH 00/12] Fix and update HOWTO Korean translation

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 17:30 +0200
Subject[PATCH 00/12] Fix and update HOWTO Korean translation
Message-ID<suJVD-7tM-3@gated-at.bofh.it>
This patchset applies ReST conversion effort for HOWTO document to its Korean
translation.  It also contains fixup of trivial nitpicks in the document and
the translation.

All patches are based on v4.9-rc1.

SeongJae Park (12):
  Documentation/HOWTO: Mark subsection in rst format
  ko_KR/HOWTO: Fix a typo: s/Linux Torvalds/Linus Torvalds
  ko_KR/HOWTO: Fix subtitles style
  ko_KR/HOWTO: Update obsolete link to bugzilla faq
  ko_KR/HOWTO: Convert to ReST notation
  ko_KR/HOWTO: Add cross-references to other documents
  ko_KR/HOWTO: Update information about generating documentation
  ko_KR/HOWTO: Improve some markups to make it visually better
  ko_KR/HOWTO: Adjust external link references
  ko_KR/HOWTO: Clean up bare :: lines
  ko_KR/HOWTO: Add whitespace between URL and text
  ko_KR/HOWTO: Mark subsection in rst format

 Documentation/HOWTO       |  15 +++--
 Documentation/ko_KR/HOWTO | 162 ++++++++++++++++++++++++++++++----------------
 2 files changed, 117 insertions(+), 60 deletions(-)

-- 
2.10.0

[toc] | [next] | [standalone]

#1506078 — [PATCH 07/12] ko_KR/HOWTO: Update information about generating documentation

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 17:30 +0200
Subject[PATCH 07/12] ko_KR/HOWTO: Update information about generating documentation
Message-ID<suJVF-7tM-51@gated-at.bofh.it>
In reply to#1506077
This commit applies commit 43fb67a5258c ("Documentation/HOWTO: update
information about generating documentation") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 Documentation/ko_KR/HOWTO | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO
index a8991333790f..f1e2c4718aad 100644
--- a/Documentation/ko_KR/HOWTO
+++ b/Documentation/ko_KR/HOWTO
@@ -176,21 +176,35 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
     패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게
     적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다.
 
-커널은 소스 코드 그 자체에서 자동적으로 만들어질 수 있는 많은 문서들을
-가지고 있다. 이것은 커널 내의 API에 대한 모든 설명, 그리고 락킹을
-올바르게 처리하는 법에 관한 규칙을 포함하고 있다. 이 문서는
-Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, HTML,
-그리고 man 페이지들로 다음과 같이 실행하여 만들어 진다.
+커널은 소스 코드 그 자체에서 또는 이것과 같은 ReStructuredText 마크업 (ReST) 을
+통해 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의
+API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법에 관한 규칙을 포함하고
+있다.
+
+모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF
+나 HTML 의 형태로 만들어질 수 있다.
 
 ::
 
          make pdfdocs
-         make psdocs
          make htmldocs
-         make mandocs
 
-각각의 명령을 메인 커널 소스 디렉토리로부터 실행한다.
+ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다.  해당
+문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다:
+
+::
+
+         make latexdocs
+         make epubdocs
+
+현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
+문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
+Postscript 나 man page 로도 만들어질 수 있다:
+
+::
 
+         make psdocs
+         make mandocs
 
 커널 개발자가 되는 것
 ---------------------
-- 
2.10.0

[toc] | [prev] | [next] | [standalone]

#1506079 — [PATCH 10/12] ko_KR/HOWTO: Clean up bare :: lines

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 17:30 +0200
Subject[PATCH 10/12] ko_KR/HOWTO: Clean up bare :: lines
Message-ID<suJVF-7tM-67@gated-at.bofh.it>
In reply to#1506077
This commit applies commit 1b49ecf2f3be ("docs: Clean up bare :: lines")
to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 Documentation/ko_KR/HOWTO | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO
index 9898e14c9cc3..33d9f0fcd7ed 100644
--- a/Documentation/ko_KR/HOWTO
+++ b/Documentation/ko_KR/HOWTO
@@ -180,26 +180,20 @@ API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법
 있다.
 
 모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF
-나 HTML 의 형태로 만들어질 수 있다.
-
-::
+나 HTML 의 형태로 만들어질 수 있다::
 
          make pdfdocs
          make htmldocs
 
 ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다.  해당
-문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다:
-
-::
+문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다::
 
          make latexdocs
          make epubdocs
 
 현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
 문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
-Postscript 나 man page 로도 만들어질 수 있다:
-
-::
+Postscript 나 man page 로도 만들어질 수 있다::
 
          make psdocs
          make mandocs
-- 
2.10.0

[toc] | [prev] | [next] | [standalone]

#1506081 — [PATCH 11/12] ko_KR/HOWTO: Add whitespace between URL and text

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 17:30 +0200
Subject[PATCH 11/12] ko_KR/HOWTO: Add whitespace between URL and text
Message-ID<suJVF-7tM-63@gated-at.bofh.it>
In reply to#1506077
Because few sentences has no whitespace between URL and text, document
fails to parse the URL from it.  This commit adds whitespace between
them to fix the problem.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 Documentation/ko_KR/HOWTO | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO
index 33d9f0fcd7ed..a3f54c23f61d 100644
--- a/Documentation/ko_KR/HOWTO
+++ b/Documentation/ko_KR/HOWTO
@@ -260,7 +260,7 @@ Postscript 나 man page 로도 만들어질 수 있다::
 
 4.x 커널 트리
 -------------
-4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org의
+4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의
 pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
 
   - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
@@ -377,8 +377,8 @@ https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그
 점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은
 다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다.
 
-이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org를
-참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
+이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org
+를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
 bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다)
 bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다)
 에 등록하면 된다.
-- 
2.10.0

[toc] | [prev] | [next] | [standalone]

#1506082 — [PATCH 03/12] ko_KR/HOWTO: Fix subtitles style

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 17:30 +0200
Subject[PATCH 03/12] ko_KR/HOWTO: Fix subtitles style
Message-ID<suJVF-7tM-61@gated-at.bofh.it>
In reply to#1506077
This commit fixes subtitles style.  It aligns them with their header,
adjust blank lines between them properly.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 Documentation/ko_KR/HOWTO | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO
index f14ccada9465..0b13d0a78446 100644
--- a/Documentation/ko_KR/HOWTO
+++ b/Documentation/ko_KR/HOWTO
@@ -229,8 +229,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H
   - 4.x - 통합 테스트를 위한 next 커널 트리
 
 4.x 커널 트리
----------------
-
+-------------
 4.x 커널들은 Linus Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/
 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
   - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
@@ -261,8 +260,7 @@ Andrew Morton의 글이 있다.
          배포되는 것은 아니기 때문이다."
 
 4.x.y - 안정 커널 트리
-------------------------
-
+----------------------
 3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x
 커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을
 포함한다.
@@ -280,9 +278,8 @@ Andrew Morton의 글이 있다.
 종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게
 진행되는지를 설명한다.
 
-
 4.x -git 패치들
-------------------
+---------------
 git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의
 커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며
 Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도
@@ -311,7 +308,7 @@ Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인
 http://patchwork.ozlabs.org/ 에 나열되어 있다.
 
 4.x - 통합 테스트를 위한 next 커널 트리
------------------------------------------
+---------------------------------------
 서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합
 테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의
 매일 받아가는 특수한 테스트 저장소가 존재한다:
@@ -321,8 +318,10 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다.
 가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를
 수행하는 것도 좋을 것이다.
 
+
 버그 보고
 ---------
+
 bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는 곳이다.
 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 권장한다.
 kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
@@ -405,7 +404,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
 
 
 커뮤니티와 협력하는 법
---------------------
+----------------------
 
 커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이
 받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다.
@@ -443,7 +442,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
 
 
 커널 커뮤니티와 기업 조직간의 차이점
------------------------------------------------------------------
+------------------------------------
 커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의
 문제를 피하기 위한 목록이 있다.
   여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 :
-- 
2.10.0

[toc] | [prev] | [next] | [standalone]

#1506084 — [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 17:30 +0200
Subject[PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format
Message-ID<suJVF-7tM-71@gated-at.bofh.it>
In reply to#1506077
Subsections in HOWTO is not marked in rst format.  This commit specifies
them in rst format.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 Documentation/HOWTO | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index 5f042349f987..5cf6ea84a6f8 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -254,7 +254,8 @@ branches.  These different branches are:
   - the 4.x -next kernel tree for integration tests
 
 4.x kernel tree
------------------
+~~~~~~~~~~~~~~~
+
 4.x kernels are maintained by Linus Torvalds, and can be found on
 https://kernel.org in the pub/linux/kernel/v4.x/ directory.  Its development
 process is as follows:
@@ -289,7 +290,8 @@ mailing list about kernel releases:
 	preconceived timeline."*
 
 4.x.y -stable kernel tree
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Kernels with 3-part versions are -stable kernels. They contain
 relatively small and critical fixes for security problems or significant
 regressions discovered in a given 4.x kernel.
@@ -312,7 +314,8 @@ documents what kinds of changes are acceptable for the -stable tree, and
 how the release process works.
 
 4.x -git patches
-----------------
+~~~~~~~~~~~~~~~~
+
 These are daily snapshots of Linus' kernel tree which are managed in a
 git repository (hence the name.) These patches are usually released
 daily and represent the current state of Linus' tree.  They are more
@@ -320,7 +323,8 @@ experimental than -rc kernels since they are generated automatically
 without even a cursory glance to see if they are sane.
 
 Subsystem Specific kernel trees and patches
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The maintainers of the various kernel subsystems --- and also many
 kernel subsystem developers --- expose their current state of
 development in source repositories.  That way, others can see what is
@@ -344,7 +348,8 @@ accepted, or rejected.  Most of these patchwork sites are listed at
 https://patchwork.kernel.org/.
 
 4.x -next kernel tree for integration tests
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Before updates from subsystem trees are merged into the mainline 4.x
 tree, they need to be integration-tested.  For this purpose, a special
 testing repository exists into which virtually all subsystem trees are
-- 
2.10.0

[toc] | [prev] | [next] | [standalone]

#1506101 — Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2016-10-21 17:50 +0200
SubjectRe: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format
Message-ID<suKf0-7AT-49@gated-at.bofh.it>
In reply to#1506084
Em Sat, 22 Oct 2016 00:19:46 +0900
SeongJae Park <sj38.park@gmail.com> escreveu:

> Subsections in HOWTO is not marked in rst format.  This commit specifies
> them in rst format.
> 
> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> ---
>  Documentation/HOWTO | 15 ++++++++++-----
>  1 file changed, 10 insertions(+), 5 deletions(-)

There are already patches converting HOWTO to ReST applied upstream:

commit 1b49ecf2f3be358882bb97652ba50ae808c0ba8f
Author: Jonathan Corbet <corbet@lwn.net>
Date:   Tue Sep 20 18:46:36 2016 -0600

    docs: Clean up bare :: lines
    
    Mauro's patch set introduced some bare :: lines; these can be represented
    by a double colon at the end of the preceding text line.  The result looks
    a little less weird and is less verbose.
    
    Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit f1eebe92c2653e8fc3760577e53befdc9b62ef26
Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Date:   Mon Sep 19 08:07:59 2016 -0300

    Documentation/HOWTO: adjust external link references
    
    - A few link references were missing http://
    - Several sites are now redirecting to https protocol. On such
      cases, just use the https URL.
    
    NOTE: all URLs were checked and they're pointing to the right places.
    
    Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
    Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit 34fed7e7e0e56f885f309e8892a3571400072e37
Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Date:   Mon Sep 19 08:07:58 2016 -0300

    Documentation/HOWTO: improve some markups to make it visually better
    
    Do a series of minor improvements at the ReST output format:
    
    - Instead of using the quote blocks (::) for quotes, use
    italics. That looks nicer on epub (and html) output, as
    no scroll bar will be added. Also, it will adjust line
    breaks on the text automatically.
    
    - Add a missing reference to SubmittingPatches.rst and use
    **foo** instead of _foo_.
    
    - use bold for "The Perfect Patch" by removing a newline.
    
    Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
    Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit 43fb67a5258c0f3d1d869cb7d72617d87b257c62
Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Date:   Mon Sep 19 08:07:57 2016 -0300

    Documentation/HOWTO: update information about generating documentation
    
    The description there are pre-Sphinx. Update it to cover the
    new way.
    
    Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
    Signed-off-by: Jonathan Corbet <corbet@lwn.net>


There's also a series of patches pending merge that moves it
Documentation/process/howto.rst and add to this book:

	https://mchehab.fedorapeople.org/kernel_docs/process/howto.html


Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1506145 — Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 18:50 +0200
SubjectRe: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format
Message-ID<suLb4-8f6-37@gated-at.bofh.it>
In reply to#1506101
On Sat, Oct 22, 2016 at 12:45 AM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
> Em Sat, 22 Oct 2016 00:19:46 +0900
> SeongJae Park <sj38.park@gmail.com> escreveu:
>
>> Subsections in HOWTO is not marked in rst format.  This commit specifies
>> them in rst format.
>>
>> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
>> ---
>>  Documentation/HOWTO | 15 ++++++++++-----
>>  1 file changed, 10 insertions(+), 5 deletions(-)
>
> There are already patches converting HOWTO to ReST applied upstream:

This patchset is not to replace the patches but to be applied on top of the
patches.

>
> commit 1b49ecf2f3be358882bb97652ba50ae808c0ba8f
> Author: Jonathan Corbet <corbet@lwn.net>
> Date:   Tue Sep 20 18:46:36 2016 -0600
>
>     docs: Clean up bare :: lines
>
>     Mauro's patch set introduced some bare :: lines; these can be represented
>     by a double colon at the end of the preceding text line.  The result looks
>     a little less weird and is less verbose.
>
>     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>
> commit f1eebe92c2653e8fc3760577e53befdc9b62ef26
> Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Date:   Mon Sep 19 08:07:59 2016 -0300
>
>     Documentation/HOWTO: adjust external link references
>
>     - A few link references were missing http://
>     - Several sites are now redirecting to https protocol. On such
>       cases, just use the https URL.
>
>     NOTE: all URLs were checked and they're pointing to the right places.
>
>     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>
> commit 34fed7e7e0e56f885f309e8892a3571400072e37
> Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Date:   Mon Sep 19 08:07:58 2016 -0300
>
>     Documentation/HOWTO: improve some markups to make it visually better
>
>     Do a series of minor improvements at the ReST output format:
>
>     - Instead of using the quote blocks (::) for quotes, use
>     italics. That looks nicer on epub (and html) output, as
>     no scroll bar will be added. Also, it will adjust line
>     breaks on the text automatically.
>
>     - Add a missing reference to SubmittingPatches.rst and use
>     **foo** instead of _foo_.
>
>     - use bold for "The Perfect Patch" by removing a newline.
>
>     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>
> commit 43fb67a5258c0f3d1d869cb7d72617d87b257c62
> Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Date:   Mon Sep 19 08:07:57 2016 -0300
>
>     Documentation/HOWTO: update information about generating documentation
>
>     The description there are pre-Sphinx. Update it to cover the
>     new way.
>
>     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>
>
> There's also a series of patches pending merge that moves it
> Documentation/process/howto.rst and add to this book:
>
>         https://mchehab.fedorapeople.org/kernel_docs/process/howto.html

AFAIU, `The development process` section has subsections but they are marked as
sections.  That's what this patchset is trying to solve.  Looks like the
problem is still in the pending patches, too.  If you would like, I will resend
this patch after merging of the pending patches, though it would be no big
problem to merge this little patch before it.


Thanks,
SeongJae Park

>
>
> Thanks,
> Mauro

[toc] | [prev] | [next] | [standalone]

#1506162 — Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2016-10-21 19:30 +0200
SubjectRe: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format
Message-ID<suLNL-hj-5@gated-at.bofh.it>
In reply to#1506145
Em Sat, 22 Oct 2016 01:42:00 +0900
SeongJae Park <sj38.park@gmail.com> escreveu:

> On Sat, Oct 22, 2016 at 12:45 AM, Mauro Carvalho Chehab
> <mchehab@s-opensource.com> wrote:
> > Em Sat, 22 Oct 2016 00:19:46 +0900
> > SeongJae Park <sj38.park@gmail.com> escreveu:
> >  
> >> Subsections in HOWTO is not marked in rst format.  This commit specifies
> >> them in rst format.
> >>
> >> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> >> ---
> >>  Documentation/HOWTO | 15 ++++++++++-----
> >>  1 file changed, 10 insertions(+), 5 deletions(-)  
> >
> > There are already patches converting HOWTO to ReST applied upstream:  
> 
> This patchset is not to replace the patches but to be applied on top of the
> patches.
> 
> >
> > commit 1b49ecf2f3be358882bb97652ba50ae808c0ba8f
> > Author: Jonathan Corbet <corbet@lwn.net>
> > Date:   Tue Sep 20 18:46:36 2016 -0600
> >
> >     docs: Clean up bare :: lines
> >
> >     Mauro's patch set introduced some bare :: lines; these can be represented
> >     by a double colon at the end of the preceding text line.  The result looks
> >     a little less weird and is less verbose.
> >
> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> >
> > commit f1eebe92c2653e8fc3760577e53befdc9b62ef26
> > Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > Date:   Mon Sep 19 08:07:59 2016 -0300
> >
> >     Documentation/HOWTO: adjust external link references
> >
> >     - A few link references were missing http://
> >     - Several sites are now redirecting to https protocol. On such
> >       cases, just use the https URL.
> >
> >     NOTE: all URLs were checked and they're pointing to the right places.
> >
> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> >
> > commit 34fed7e7e0e56f885f309e8892a3571400072e37
> > Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > Date:   Mon Sep 19 08:07:58 2016 -0300
> >
> >     Documentation/HOWTO: improve some markups to make it visually better
> >
> >     Do a series of minor improvements at the ReST output format:
> >
> >     - Instead of using the quote blocks (::) for quotes, use
> >     italics. That looks nicer on epub (and html) output, as
> >     no scroll bar will be added. Also, it will adjust line
> >     breaks on the text automatically.
> >
> >     - Add a missing reference to SubmittingPatches.rst and use
> >     **foo** instead of _foo_.
> >
> >     - use bold for "The Perfect Patch" by removing a newline.
> >
> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> >
> > commit 43fb67a5258c0f3d1d869cb7d72617d87b257c62
> > Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > Date:   Mon Sep 19 08:07:57 2016 -0300
> >
> >     Documentation/HOWTO: update information about generating documentation
> >
> >     The description there are pre-Sphinx. Update it to cover the
> >     new way.
> >
> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> >
> >
> > There's also a series of patches pending merge that moves it
> > Documentation/process/howto.rst and add to this book:
> >
> >         https://mchehab.fedorapeople.org/kernel_docs/process/howto.html  
> 
> AFAIU, `The development process` section has subsections but they are marked as
> sections.  That's what this patchset is trying to solve.  Looks like the
> problem is still in the pending patches, too.  If you would like, I will resend
> this patch after merging of the pending patches, though it would be no big
> problem to merge this little patch before it.

There's no real difference on using something like:

	foo
	===

	bar
	---

or

	foo
	~~~

	bar
	===

Sphinx just gets the first tag and use it for level 1 indentation, the
next one for level 2, etc.

See:
	http://www.sphinx-doc.org/en/stable/rest.html

	"Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.

	...

	"Of course, you are free to use your own marker characters
	(see the reST documentation), and use a deeper nesting level, 
	but keep in mind that most target formats (HTML, LaTeX) have
	a limited supported nesting depth."


So, the only real limit is the number of indentation levels that the
document can have.

It proposes an style guide, but I don't see any sense on enforcing
an specific style here. Actually, not enforcing one is, IMHO, a
good thing, because we can always switch the indentation level
by simply including a document on a TOC. So, it is easy to promote
or to demote a document, by just changing the .. toctable:: where it
belongs.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1506193 — Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-21 20:00 +0200
SubjectRe: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format
Message-ID<suMgT-so-9@gated-at.bofh.it>
In reply to#1506162
On Sat, Oct 22, 2016 at 2:25 AM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
> Em Sat, 22 Oct 2016 01:42:00 +0900
> SeongJae Park <sj38.park@gmail.com> escreveu:
>
>> On Sat, Oct 22, 2016 at 12:45 AM, Mauro Carvalho Chehab
>> <mchehab@s-opensource.com> wrote:
>> > Em Sat, 22 Oct 2016 00:19:46 +0900
>> > SeongJae Park <sj38.park@gmail.com> escreveu:
>> >
>> >> Subsections in HOWTO is not marked in rst format.  This commit specifies
>> >> them in rst format.
>> >>
>> >> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
>> >> ---
>> >>  Documentation/HOWTO | 15 ++++++++++-----
>> >>  1 file changed, 10 insertions(+), 5 deletions(-)
>> >
>> > There are already patches converting HOWTO to ReST applied upstream:
>>
>> This patchset is not to replace the patches but to be applied on top of the
>> patches.
>>
>> >
>> > commit 1b49ecf2f3be358882bb97652ba50ae808c0ba8f
>> > Author: Jonathan Corbet <corbet@lwn.net>
>> > Date:   Tue Sep 20 18:46:36 2016 -0600
>> >
>> >     docs: Clean up bare :: lines
>> >
>> >     Mauro's patch set introduced some bare :: lines; these can be represented
>> >     by a double colon at the end of the preceding text line.  The result looks
>> >     a little less weird and is less verbose.
>> >
>> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>> >
>> > commit f1eebe92c2653e8fc3760577e53befdc9b62ef26
>> > Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> > Date:   Mon Sep 19 08:07:59 2016 -0300
>> >
>> >     Documentation/HOWTO: adjust external link references
>> >
>> >     - A few link references were missing http://
>> >     - Several sites are now redirecting to https protocol. On such
>> >       cases, just use the https URL.
>> >
>> >     NOTE: all URLs were checked and they're pointing to the right places.
>> >
>> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>> >
>> > commit 34fed7e7e0e56f885f309e8892a3571400072e37
>> > Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> > Date:   Mon Sep 19 08:07:58 2016 -0300
>> >
>> >     Documentation/HOWTO: improve some markups to make it visually better
>> >
>> >     Do a series of minor improvements at the ReST output format:
>> >
>> >     - Instead of using the quote blocks (::) for quotes, use
>> >     italics. That looks nicer on epub (and html) output, as
>> >     no scroll bar will be added. Also, it will adjust line
>> >     breaks on the text automatically.
>> >
>> >     - Add a missing reference to SubmittingPatches.rst and use
>> >     **foo** instead of _foo_.
>> >
>> >     - use bold for "The Perfect Patch" by removing a newline.
>> >
>> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>> >
>> > commit 43fb67a5258c0f3d1d869cb7d72617d87b257c62
>> > Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> > Date:   Mon Sep 19 08:07:57 2016 -0300
>> >
>> >     Documentation/HOWTO: update information about generating documentation
>> >
>> >     The description there are pre-Sphinx. Update it to cover the
>> >     new way.
>> >
>> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> >     Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>> >
>> >
>> > There's also a series of patches pending merge that moves it
>> > Documentation/process/howto.rst and add to this book:
>> >
>> >         https://mchehab.fedorapeople.org/kernel_docs/process/howto.html
>>
>> AFAIU, `The development process` section has subsections but they are marked as
>> sections.  That's what this patchset is trying to solve.  Looks like the
>> problem is still in the pending patches, too.  If you would like, I will resend
>> this patch after merging of the pending patches, though it would be no big
>> problem to merge this little patch before it.
>
> There's no real difference on using something like:
>
>         foo
>         ===
>
>         bar
>         ---
>
> or
>
>         foo
>         ~~~
>
>         bar
>         ===
>
> Sphinx just gets the first tag and use it for level 1 indentation, the
> next one for level 2, etc.
>
> See:
>         http://www.sphinx-doc.org/en/stable/rest.html
>
>         "Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.
>
>         ...
>
>         "Of course, you are free to use your own marker characters
>         (see the reST documentation), and use a deeper nesting level,
>         but keep in mind that most target formats (HTML, LaTeX) have
>         a limited supported nesting depth."
>
>
> So, the only real limit is the number of indentation levels that the
> document can have.
>
> It proposes an style guide, but I don't see any sense on enforcing
> an specific style here. Actually, not enforcing one is, IMHO, a
> good thing, because we can always switch the indentation level
> by simply including a document on a TOC. So, it is easy to promote
> or to demote a document, by just changing the .. toctable:: where it
> belongs.

Well... `kernel-documentation.rst`, the document that I considered, says as
below:

```
Specific guidelines for the kernel documentation
------------------------------------------------

Here are some specific guidelines for the kernel documentation:

* Please don't go overboard with reStructuredText markup. Keep it simple.

* Please stick to this order of heading adornments:

  1. ``=`` with overline for document title::

       ==============
       Document title
       ==============

  2. ``=`` for chapters::

       Chapters
       ========

  3. ``-`` for sections::

       Section
       -------

  4. ``~`` for subsections::

       Subsection
       ~~~~~~~~~~

  Although RST doesn't mandate a specific order ("Rather than imposing a fixed
  number and order of section title adornment styles, the order enforced will be
  the order as encountered."), having the higher levels the same overall makes
  it easier to follow the documents.
```

In short, it provides clear guideline though it also awares the meaningless of
tags order in rst.  That's why I thought it would be better to use `~~~~` for
subsections in this case.  After all, the sections in this case seems obviously
intended to be subsection of `The development process` section.   If I am
missing something, please let me know.


Thanks,
SeongJae Park


>
> Thanks,
> Mauro

[toc] | [prev] | [next] | [standalone]

#1506278

FromJonathan Corbet <corbet@lwn.net>
Date2016-10-21 22:50 +0200
Message-ID<suOVj-2gP-17@gated-at.bofh.it>
In reply to#1506077
On Sat, 22 Oct 2016 00:19:45 +0900
SeongJae Park <sj38.park@gmail.com> wrote:

> This patchset applies ReST conversion effort for HOWTO document to its Korean
> translation.  It also contains fixup of trivial nitpicks in the document and
> the translation.

Thanks for doing these; let's definitely get this work in soon.  I have
just a few comments:

- I think that bringing the (English) HOWTO into line with our posted
  conventions makes sense, I'm happy to take patches to do that.  Let's
  do that separately from the translation changes, though, and let's
  think in terms of building on Mauro's work.  Either send me a patch
  after his stuff is in, or send one for him to collect and send with the
  rest, whatever works best for everybody else.

- You do the ReST conversion, but don't take the final step and actually
  bring the document into the Sphinx world.

I've been thinking that it would be good to make a translations/
top-level directory and move the various translated documents underneath
that.  Then we could maybe make a translations/index.rst and create a
special subbook for those documents.  Make sense?

If at all possible, I'd like an ack from somebody else who understands
Korean.  Minchan, I see you on the CC, can you help out? :)  With that, I
see no reason not to apply parts 2-12.

Thanks,

jon

[toc] | [prev] | [next] | [standalone]

#1506368

FromSeongJae Park <sj38.park@gmail.com>
Date2016-10-22 03:50 +0200
Message-ID<suTBD-5e7-1@gated-at.bofh.it>
In reply to#1506278
On Sat, Oct 22, 2016 at 5:47 AM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Sat, 22 Oct 2016 00:19:45 +0900
> SeongJae Park <sj38.park@gmail.com> wrote:
>
>> This patchset applies ReST conversion effort for HOWTO document to its Korean
>> translation.  It also contains fixup of trivial nitpicks in the document and
>> the translation.
>
> Thanks for doing these; let's definitely get this work in soon.  I have
> just a few comments:

Thanks for your opinion! :)


>
> - I think that bringing the (English) HOWTO into line with our posted
>   conventions makes sense, I'm happy to take patches to do that.  Let's
>   do that separately from the translation changes, though, and let's
>   think in terms of building on Mauro's work.  Either send me a patch
>   after his stuff is in, or send one for him to collect and send with the
>   rest, whatever works best for everybody else.

Agree.  I will send you the patch again after Mauro's work be merged.


>
> - You do the ReST conversion, but don't take the final step and actually
>   bring the document into the Sphinx world.
>
> I've been thinking that it would be good to make a translations/
> top-level directory and move the various translated documents underneath
> that.  Then we could maybe make a translations/index.rst and create a
> special subbook for those documents.  Make sense?

Yes, it makes sense to me.  I will send patches for that soon.


Thanks,
SeongJae Park

>
> If at all possible, I'd like an ack from somebody else who understands
> Korean.  Minchan, I see you on the CC, can you help out? :)  With that, I
> see no reason not to apply parts 2-12.
>
> Thanks,
>
> jon

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web