Pod6 표

Pod6 표 (tables)

Raku의 문서 표기법인 Pod6에서 표를 어떻게 쓰는지 다루는 문서예요. Pod6 표의 공식 스펙은 Documentation specification에 있는데, Pod6 스펙이 아직 완전히 제대로 처리되지는 않아서 몇몇 프로젝트가 이를 바로잡는 중이에요. 그중 하나가 Pod6 표를 제대로 처리하도록 하는 작업이죠.

출처: Raku Docs - Pod6 tables

이 문서는 그 노력의 일환으로 Pod6 표의 현재 상태를 예를 들어 설명해요. 유효한 표, 유효하지 않은 표, 그리고 예상 밖의 표(즉, 성급하게 만든 탓에 사용자가 의도한 것과 다르게 해석되는 유효한 표)를 각각 보여줍니다.

제약(Restrictions)

  1. 유효한 열 구분자는 보이는(visible) 구분자 ' | ' 또는 ' + '이거나(양쪽에 최소 하나의 공백 필요), 보이지 않는(invisible) 구분자 즉 두 개 이상의 연속된 공백(WS) 문자예요(예: ' '). 열 구분자는 보통 표의 왼쪽·오른쪽 끝에서는 구분자로 인식되지 않아요. 다만 오른쪽에 위치한 구분자 하나는 다른 행의 셀 개수에 따라 빈 셀을 하나 이상 만들 수 있어요. 셀 데이터의 일부로 쓰인 파이프나 플러스 문자는 백슬래시로 이스케이프하지 않으면('\|' 또는 '\\+') 의도하지 않은 열을 만들어 낸다는 점을 주의하세요.
  2. 같은 표에서 보이는 구분자와 보이지 않는 구분자를 섞어 쓰는 것은 불법이에요.
  3. 유효한 행 구분자는 '_', '-', '+', ' ', '|', '='뿐이에요.
  4. 행 구분자가 연속으로 두 줄 이상 오는 것은 불법이에요.
  5. 표의 맨 앞이나 맨 뒤에 오는 행 구분자 줄은 경고를 발생시켜요.
  6. 표 셀 안의 서식 블록은 현재 무시되고 일반 텍스트로 처리돼요.

힌트: 개발 중에는 RAKUDO_POD6_TABLE_DEBUG 환경 변수를 쓰면, Rakudo가 Pod::To::HTML, Pod::To::Text, Pod::To::Markdown 같은 렌더러에 넘기기 전에 여러분의 표를 어떻게 해석하는지 보여줘요.

모범 사례(Best practices)

힌트: 아래 모범 사례를 지키지 않으면 표 행을 추가로 반복 처리해야 해서 표 처리에 더 시간이 걸릴 수 있어요.

  1. WS를 열 구분자로 쓰는 것은 취약해서, 단순한 표에서만 쓰는 게 좋아요. 아래 예상 밖의 표 절이 그 문제를 보여줘요.

  2. 표의 열과 행을 신중하게 정렬하세요. 이후 모범 사례의 예시를 참고하세요.

  3. 표에 시각적인 테두리를 쓰지 마세요.

  4. 헤딩과 한 줄 또는 여러 줄 내용을 가진 표라면, 헤딩 뒤의 행 구분자로 연속된 등호 '='를 하나 이상 쓰고, 내용 부분의 행 구분자로는 연속된 하이픈 '-'을 하나 이상 쓰세요. 예를 들어

    • 헤딩 + 한 줄 또는 여러 줄 내용
    =begin table
 hdr col 0 | hdr col 1
 ======================
 row 0     | row 0
 col 0     | col 1
 ----------------------
 row 1     | row 1
 col 0     | col 1
 ----------------------
=end table
    • 헤딩 + 한 줄 내용
    =begin table
 hdr col 0   | hdr col 1
 ======================
 row 0 col 0 | row 0 col 1
 row 1 col 0 | row 1 col 1
=end table

  5. 헤딩이 없고 여러 줄 내용을 가진 표라면, 내용 부분의 행 구분자로 연속된 하이픈 '-'을 하나 이상 쓰세요. 예를 들어

    =begin table
 row 0       | row 0
 col 0       | col 1
 ----------------------
 row 1 col 0 | row 1 col 1
=end table

  6. 행이 많고 여러 줄 내용이 없는 표라면 행 구분자를 쓰지 않아도 괜찮아요. 하지만 여러 줄 내용을 가진 행이 하나 이상 있다면, 내용 행 사이마다 행 구분자 줄(보이든 안 보이든)을 넣는 것이 확실한 결과를 얻는 데 더 쉬워요.

  7. 의도적으로 비워둔 셀에는 열 구분자를 반드시 넣으세요. 그렇지 않으면 짧은 행이 빈 셀로 채워진다는 경고가 나올 수 있어요. (표 행은 항상 가장 많은 셀을 가진 행과 같은 수의 셀을 가져요. 짧은 행은 오른쪽에 빈 셀로 채워지며 경고를 발생시킵니다.)

  8. 표에 캡션을 추가하려면 =begin table 행에 이렇게 넣을 수 있어요.

    =begin table :caption<My Tasks>
mow lawn
take out trash
=end table

    좋은 방법은 아니지만, 현재 아래 예처럼 캡션을 정의하는 대체 방법도 사용되고 있어요.

    =begin table :config{caption => "My Tasks"}
mow lawn
take out trash
=end table

    config 해시에 캡션을 넣는 이 대체 방법은 :caption 방법이 구현되기 전에 필요했던 방식이에요. 이제는 그 방법이 더 이상 사용되지 않고(deprecated), 곧 나올 6.d 버전에서는 경고를, 6.e 버전에서는 예외를 발생시킬 거예요.

유효한 표(Valid tables)

아래는 Specification Tests에서 가져온 유효한 표의 예시예요.

=begin table
        The Shoveller   Eddie Stevens     King Arthur's singing shovel
        Blue Raja       Geoffrey Smith    Master of cutlery
        Mr Furious      Roy Orson         Ticking time bomb of fury
        The Bowler      Carol Pinnsler    Haunted bowling ball
=end table

=table
    Constants           1
    Variables           10
    Subroutines         33
    Everything else     57

=for table
    mouse    | mice
    horse    | horses
    elephant | elephants

=table
    Animal | Legs |    Eats
    =======================
    Zebra  +   4  + Cookies
    Human  +   2  +   Pizza
    Shark  +   0  +    Fish

=table
        Superhero     | Secret          |
                      | Identity        | Superpower
        ==============|=================|================================
        The Shoveller | Eddie Stevens   | King Arthur's singing shovel

=begin table

                        Secret
        Superhero       Identity          Superpower
        =============   ===============   ===================
        The Shoveller   Eddie Stevens     King Arthur's
                                          singing shovel

        Blue Raja       Geoffrey Smith    Master of cutlery

        Mr Furious      Roy Orson         Ticking time bomb
                                          of fury

        The Bowler      Carol Pinnsler    Haunted bowling ball
=end table

=table
    X | O |
   ---+---+---
      | X | O
   ---+---+---
      |   | X

=table
    X   O
   ===========
        X   O
   ===========
            X

=begin table

foo
bar

=end table

유효하지 않은 표(Invalid tables)

아래는 유효하지 않은 표의 예시로, 파싱 중에 처리되지 않은 예외를 일으켜야 해요.

  • 같은 행에서 열 구분자 유형을 섞어 쓰는 것은 허용되지 않아요.

    =begin table
r0c0 +  r0c1 | r0c3
=end table

  • 같은 표에서 보이는 구분자와 공백 구분자를 섞어 쓰는 것은 허용되지 않아요.

    =begin table
r0c0 +  r0c1 | r0c3
r1c0    r0c1   r0c3
=end table

  • 두 개의 연속된 내부 행 구분자는 허용되지 않아요.

    =begin table
r0c0 |  r0c1
============
============
r1c0 |  r1c1
=end table

예상 밖의 표(Unexpected tables)

아래는 유효한 표지만, 아마도 두 열을 의도하고 만든 것들이에요. 그런데 열이 잘 정렬되어 있지 않아서 각각 한 열짜리 표로 파싱되죠.

  • WS 열 구분자를 쓴 정렬되지 않은 열:

    두 번째 행의 두 단어가 하나의 WS로만 분리된 점을 보세요. 열 구분이 되려면 두 개 이상의 인접한 WS 문자가 필요한데, 그도 못 미치죠. 이것은 유효한 표지만 한 열짜리 표로 파싱될 거예요.

    =begin table
r0c0    r0c1
 r1c0 r0c1
=end table

  • 보이는 열 구분자를 쓴 정렬되지 않은 열:

    두 번째 행의 두 단어가 보이는 문자 '|'로 분리되어 있는데, 양쪽에 인접한 WS 문자가 없어서 구분자로 인식되지 않아요. 이 역시 합법적인 표지만 결과는 사용자가 의도한 것과 다르죠. 첫 번째 행은 두 열인데 두 번째 행은 한 열이라, 두 번째 행에 빈 두 번째 열이 생기게 돼요.

    =begin table
r0c0  |  r0c1
 r1c0 |r0c1
=end table