Hướng Dẫn về Kiểu Cách của Dấu Đánh (Markup Style Guide)

Trang này bao gồm các quy ước để viết và sử dụng cú pháp dấu đánh trong reStructuredText (RST).

Quy Ước (Conventions)

Thụt dòng ba khoảng cách trống.
Số chữ trong các dòng phải ít hơn 120 ký tự.
Sử dụng chữ nghiêng cho các tên của nút bấm/trình đơn.

Những quy ước khác:

Tránh không dùng các ký tự trong bộ phông Unicode.
Tránh xuống dòng quá nhiều (chẳng hạn, mỗi câu một dòng).

Tiêu Đề (Headings)

#################
  Document Part
#################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Ghi chú

"Parts" chỉ nên được sử dụng cho nội dung, hoặc ở các trang mục lục mà thôi.

Ghi chú

Mỗi tập tin .rst chỉ nên có một tiêu đề cho chương (*) mà thôi.

Kiểu Chữ (Text Styling)

Xin hãy xem phần khái quát về Tái Cấu Trúc Văn Bản (overview on ReStructuredText) để biết thêm thông tin về phương pháp tạo kiểu cách cho các phần tử khác nhau của tài liệu, và cách cho thêm danh sách, bảng, hình ảnh và khối mã nguồn vào. Bản Sách khảo cứu về Sphinx (Sphinx reference) là bản sẽ cung cấp thêm chi tiết sâu về nhiều cấu trúc bổ sung khác nữa.

Sau đây là các dấu đánh hữu ích để tạo kiểu cách cho văn bản:

*italic*
**bold**
``literal``

Phần Tử Giao Diện (Interface Elements)

:kbd:`LMB` -- tổ hợp phím bấm nhanh và bố trí chuột.
*Mirror* -- nhãn giao diện.
:menuselection:`3D Viewport --> Add --> Mesh --> Monkey` -- trình đơn.

Ví Dụ về Mã Nguồn (Code Samples)

Hiện cũng có chức năng nêu bật cú pháp cho ngôn ngữ nữa nếu mình cung cấp tên của ngôn ngữ lập trình, và số dòng cũng sẽ hiện ra nếu mình dùng tùy chọn ':linenos:':

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Hình Ảnh (Images)

'Figure' nên đã được sử dụng để đặt các hình ảnh minh họa:

.. figure:: /images/interface_window-system_splash_current.png

   Image caption.

Để nhất quán và để đảm bảo ảnh chụp màn hình có cùng kích thước tương tự khi đứng cạnh văn bản, các tác giả nên chụp ảnh màn hình theo cách sau:

Chuẩn bị khu vực bạn muốn chụp hình và phải đảm bảo là mình sử dụng phong cách và sắp đặt mặc định. (Trong một số trường hợp, bạn có thể không nên sử dụng cài đặt mặc định, ví dụ, nếu có tùy chọn nào đó bị ẩn khuất đi sau một hộp kiểm chẳng hạn)
Phóng vào đến mức tối đa (bấm và giữ xuống Bàn Số + (NumpadPlus) hoặc Ctrl-NCG (MMB) hoặc tương tự).
Thu nhỏ tám lần (bấm phím Dấu Trừ (-) Bàn Số (NumpadMinus) -- tám lần).
Trong một số trường hợp, bạn có thể cần phải để lại một khoảng lề nhỏ xung quanh khoảng mà bạn muốn thu chụp. Lề này sẽ là chừng khoảng 30 điểm ảnh, không cần chính xác lắm.

Cái này có thể chỉ áp dụng được trong một số phần của giao diện mà thôi, và có thể sẽ không áp dụng được trong mọi trường hợp.

Tập Tin (Files)

Không được sử dụng chữ hoa, không được để khoảng cách trống (No Caps, No Gaps)

Tên tập tin phải là chữ thường, dùng dấu gạch chân để tách biệt các từ.

Sắp Xếp Trật Tự Hợp Lý, Hữu Dụng (Sort Usefully)

Đặt tên theo thứ tự với các nhận dạng cụ thể nằm ở cuối.

Định Dạng/Hình Thức (Format)

Sử dụng .png cho các hình ảnh có màu trơn như ảnh chụp màn hình của giao diện Blender và .jpg cho hình ảnh có số lượng màu sắc biến đổi lớn, chẳng hạn như mẫu kết xuất và các ảnh chụp.

Không sử dụng các tập tin .gif hoạt họa vì những tập tin này khó bảo trì và có thể gây mất tập trung, đồng thời chúng thường có kích thước tập tin lớn. Thay vào đó, hãy sử dụng một video nếu cần (xem phần về Videos dưới đây).

Vị Trí (Location)

Đặt hình ảnh vào thư mục manual/images. Không được sử dụng các thư mục nhánh khác.

Đặt Tên (Naming)

Trong khi đặt tên các tập tin, xin hãy sử dụng các dấu gạch chân để tách phân các chương và các phần riêng biệt, đồng thời sử dụng dấu gạch ngang để tách các phần có hai hoặc nhiều từ. Các tập tin hình ảnh sẽ trông giống thế này: "chapter_subsection_sub-subsection_id.png" , chẳng hạn:

interface_splash_current.png
interface_undo-redo_last.png
interface_undo-redo_repeat-history-menu.png

Không đã được sử dụng các ký tự đặc biệt, hoặc các dấu cách trống!

Hướng Dẫn Sử Dụng (Usage Guides)

Tránh việc chỉ định độ phân giải của hình ảnh, hòng cho phép kiểu mẫu xử lý hình ảnh một cách nhất quán và cung cấp bài trí tốt nhất đối với các kích thước màn hình khác nhau.
Khi lập tài liệu cho một bảng hoặc một phần nào đó của giao diện người dùng thì tốt hơn hết là nên sử dụng một hình ảnh hiển thị toàn bộ các khu vực liên quan (thay vì nhiều hình ảnh cho mỗi biểu tượng hoặc mỗi nút) và đặt nó ở đỉnh của phần bạn đang viết, sau đó giải thích các tính năng theo thứ tự chúng xuất hiện trên hình ảnh.

Ghi chú

Bản hướng dẫn sử dụng phải được bảo quản trường kỳ, điều này rất quan trọng. Giao diện người dùng và các tùy chọn của công cụ rất hay thay đổi, vì vậy, hãy cố gắng tránh tình trạng có quá nhiều hình ảnh (đặc biệt là khi chúng không cần thiết). Nếu không, việc bảo quản sẽ trở nên một gánh nặng quá lớn.

Videos

Phim video có thể được nhúng sẵn từ máy chủ PeerTube của bản chủ Blender, tức cái mà bạn có thể thấy tại video.blender.org. Để nhúng sẵn video vào thì xin bạn hãy sử dụng chỉ thị sau đây:

.. peertube:: ID

Chỉ danh ID của phim sẽ nằm trong địa chỉ URL của phim video, chẳng hạn:

Chỉ danh nhận dạng ID cho https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c là 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

To get a new video uploaded, contact a Documentation Project Administrator or include the uploaded video in your Patch description.

Hướng Dẫn Sử Dụng (Usage Guides)

Tránh việc cho thêm các video mà nội dung chúng dựa vào giọng nói hoặc chữ viết, vì cái này rất khó phiên dịch.
Chớ gắn sẵn các phim video trợ lý học tập như một phương tiện để giải thích một tính năng nào đó của phần mềm. Bản thân nội dung của bài viết phải giải thích về nó một cách đầy đủ rồi (đương nhiên, bạn vẫn có thể kèm một liên kết đến video ở dưới cùng của trang, dưới tiêu đề trợ lý học tập).

Những Cấu Trúc Hữu Dụng (Useful Constructs)

|BLENDER_VERSION| -- Phân tích thành version hiện tại của Blender.
:abbr:`SSAO (Screen Space Ambient Occlusion)` -- Các từ viết tắt hiển thị nội dung không viết tắt dưới dạng chú giải công cụ cho người đọc nhìn thấy.
:term:`Manifold` -- Liên kết đến một mục trong bảng Thuật Ngữ (Glossary).

Đối Chiếu và Liên Kết (Cross References and Linkage)

Bạn có thể liên kết đến một tài liệu khác trong bản hướng dẫn sử dụng bằng dòng mã sau:

:doc:`The Title </section/path/to/file>`

Để liên kết đến một phần cụ thể nào đó trong một tài liệu khác (hoặc trong cùng một tài liệu), bạn có thể sử dụng các nhãn hiệu cụ thể như sau:

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

Kết nối với một tiêu đề nào đó trong cùng tập tin:

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

Kết nối với thế giới bên ngoài:

`Blender Website <https://www.blender.org>`__

Truy Cập Hướng Dẫn Sử Dụng Nhạy Cảm với Ngữ Cảnh (Context Sensitive Manual Access)

Việc liên kết một phần cụ thể của bản hướng dẫn sử dụng nội trong Blender, là một việc có thể thực hiện, bằng cách mở trình đơn ngữ cảnh (nhấp chuột phải) trên một tính chất hoặc thao tác và chọn "Hướng Dẫn Sử Dụng Trực Tuyến". Để cho phép tính năng này hoạt động thì tính năng phải được bố trí trong tài liệu. Phương pháp liên kết một tính chất, hoặc một thao tác, với một phần cụ thể nào đó của bản hướng dẫn sử dụng, là bạn phải cho thêm một thẻ liên kết tham chiếu ngoại, có chỉ danh nhận dạng ID khớp với thẻ RNA của Blender vào. Cách dễ nhất để tìm hiểu thẻ cho tính chất nào đó là mở trình đơn ngữ cảnh của tính chất/thao tác và chọn "Tham Chiếu Python Trực Tuyến" để trích xuất thẻ từ địa chỉ URL. Một số ví dụ về phương pháp hoạt động, trong các tài liệu RST, của tính năng này như thế nào, được cung cấp dưới đây:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

Đối với một thao tác:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Đọc Thêm (Further Reading)

Để học thêm về reStructuredText, xin xem:

Giới thiệu cơ bản về tái cấu trúc văn bản RST của Sphinx (Sphinx RST Primer): Giới thiệu cơ bản có chất lượng tốt.
Tham Chiếu về Tái Cấu Trúc Văn Bản RST của Công Cụ Tài Liệu Docutils (Docutils reStructuredText Reference): Các kết nối đến những tham chiếu và tài liệu cho người dùng.