Hướng Dẫn về Kiểu Cách của Dấu Đánh

Trang này bao gồm các quy ước để viết và sử dụng cú pháp dấu đánh Tái Cấu Trúc Văn Bản (RST).

Quy Ước

  • 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 tắc ước lệ 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 Đề

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

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

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

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

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

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

Ghi chú

Phần 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ữ

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

  • :kbd:`NCT (LMB)` -- tổ hợp phím bấm nhanh và bố trí chuột.

  • :abbr:`Mirror (Phản Chiếu Đối Xứng Hóa) -- nhãn giao diện.

  • :menuselection:`Cổng Nhìn 3D (3D Viewport) --> Cộng Thêm (Add) --> Khung Lưới (Mesh) --> Đầu Khỉ (Monkey)` -- trình đơn.

Ví Dụ về Mã Nguồn

Nếu mình điền tên của ngôn ngữ lập trình vào nữa thì chức năng nêu bật cú pháp cho ngôn ngữ đó cũng sẽ hoạt động, nêu bật các dòng lên, đồng thời các số dòng cũng có thể được hiện lên nếu mình dùng tùy chọn 'số dòng':

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Hình Ảnh

'Hình ảnh minh họa' 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:

  1. 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ác tùy chọn bị ẩn khuất đi sau một hộp kiểm chẳng hạn)

  2. 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ự).

  3. Thu nhỏ tám lần (bấm phím kbd:Dấu Trừ (-) Bàn Số (NumpadMinus) tám lần).

  4. Trong một số trường hợp, bạn có thể cần phải để lại một khoảng 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

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

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

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

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

Sử dụng .png cho các hình ảnh có các màu cố định 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 cao, 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ề Video bên dưới).

Vị Trí

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

Đặt Tên

Để đặt tên các tập tin, hãy sử dụng 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, ví dụ:

  • 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

  • Tránh việc chỉ định Độ phân giải của hình ảnh, hầu cho kiểu mẫu có thể 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 biệt.

  • 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, và 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 sẽ 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.

Video

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.

Để tải video mới lên thì xin hãy liên hệ với Quản Trị Viên Dự Án Viết Tài Liệu -- Documentation Project Administrator hoặc cho kèm video đã tải lên trong miêu tả của Bản Chắp Vá -- Patch của bạn.

Hướng Dẫn Sử Dụng

  • 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

  • |BLENDER_VERSION| -- Phân tích thành phiên bản hiện tại của Blender.

  • :abbr:`SSAO (Screen Space Ambient Occlusion: Tính Hấp Thụ Quang Xạ Môi Trường của Không Gian Màn Hình)` -- 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:`Đa Tạp -- 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

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 Nhập Hướng Dẫn Sử Dụng Nhạy Cảm với Ngữ Cảnh

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 thuộc tính 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 thuộc tính, 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 thuộc tính nào đó là mở trình đơn ngữ cảnh của thuộc tính/thao tác và chọn Tham Chiếu Python Trực Tuyến để trích xuất thẻ từ địa chỉ URL (Uniform Resource Locator: Định Vị Tài Nguyên Đồng Nhất. 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

Để học thêm về tái cấu trúc văn bản, 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 đường kết nối đến những tham chiếu và tài liệu cho người dùng.