Tài liệu hướng dẫn của dự án ibus-bogo

ibus-bogo là một engine xử lý gõ tiếng Việt cho IBus, một phần mềm quản lý các bộ gõ trong GNU/Linux.

ibus-bogo được viết bằng ngôn ngữ Python và sử dụng engine xử lý tiếng Việt BoGo.

Trang Github của dự án: https://github.com/BoGoEngine/ibus-bogo-python

Mục lục

Cài đặt

ibus-bogo có thể được cài đặt từ gói cài đặt hoặc (nếu bạn muốn) trực tiếp từ mã nguồn.

Từ gói cài đặt cho các bản phân phối Linux thông dụng

Người dùng Archlinux có thể cài từ gói AUR stable hoặc develop do bạn Ngô Huy cung cấp.

Người dùng Fedora có thể cài gói RPM từ RPM repo của anh Trương Anh Tuấn.

Note

Nếu bạn muốn đóng gói BoGo cho các bản phân phối khác thì đừng ngần ngại thông báo với chúng tôi để trang hướng dẫn này được cập nhật liên tục cho các bản phân phối mới nhất. :D

Từ mã nguồn

Warning

Nếu bạn chưa thành thạo Linux và chỉ muốn sử dụng BoGo thì không nên cài đặt từ mã nguồn.

ibus-bogo có sử dụng các phần mềm sau, hãy chắc chắn rằng chúng đã được cài trên máy (theo tên gói cài đặt của Debian/Ubuntu):

  • ibus 1.4.x
  • python 3.2+
  • python3-gi (pygobject)
  • python3-entrant (kiểm tra chính tả)
  • cmake
  • qt4-linguist-tools
  • pyqt4-dev-tools
  • python3-pyside
  • gir1.2-ibus-1.0 (GObject Introspection data)
  • gir1.2-wnck-3.0

Lệnh sau sẽ cài đặt tất cả các gói cần thiết:

sudo apt-get install python3 ibus cmake python3-gi pyqt4-dev-tools \
gir1.2-ibus-1.0 gir1.2-wnck-3.0 python3-pyqt4 qt4-linguist-tools \
python3-enchant

Note

Từ bản 0.4 thì ibus-bogo sử dụng PyQt4 thay vì PySide.

Sau đó bạn tải mã nguồn tại https://github.com/BoGoEngine/ibus-bogo-python/releases rồi giải nén. Hoặc dùng:

git clone https://github.com/BoGoEngine/ibus-bogo.git

Chạy lệnh sau để cài đặt:

sudo make install

Gỡ cài đặt:

sudo make uninstall

Cấu hình sau khi cài đặt

Sau khi cài đặt thì bạn cần phải thiết lập IBus để sử dụng ibus-bogo. Trước hết bạn cần mở mục Settings của IBus bằng cách nhấn vào icon trên system tray, chọn Preferences (Tùy thích) hoặc chạy lệnh ibus-setup (ảnh minh họa trên giao diện Unity của Ubuntu):

_images/menu.png

Sau đó vào tab Input Method (Kiểu gõ), ấn vào menu Select an input method (Chọn một kiểu gõ), di chuyển đến dòng Vietnamese (Tiếng Việt), chọn BoGo:

_images/select.png

Nếu bạn muốn có thể dùng nút Up (Lên) bên phải để đặt ibus-bogo làm bộ gõ mặc định:

_images/set_default.png

Với Ubuntu 13.10, trước hết bạn logout/login hoặc chạy lệnh ibus-daemon -xdr để khởi động lại IBus. Sau đó bạn sử dụng mục Text Entry trong Settings để thêm BoGo như video dưới đây:

Note

Nếu không gõ tiếng Việt được trong Skype hay các chương trình viết bằng Qt, bạn thêm các dòng sau vào file ~/.profile sau đó logout và login:

export GTK_IM_MODULE=ibus
export QT4_IM_MODULE=xim
export QT_IM_MODULE=xim
export XMODIFIERS=@im=ibus

Sử dụng

Gõ tiếng Việt

ibus-bogo hoạt động giống các bộ gõ khác dành cho IBus. Bạn chỉ cần đặt con trỏ vào những chỗ cần gõ, nhấn phím tắt của IBus (thường là control - cách, hoặc phím tắt tùy chọn của bạn) và gõ tiếng Việt bình thường.

Thay đổi kiểu gõ, bảng mã

Mặc định, ibus-bogo sử dụng kiểu gõ TELEX và bảng mã UTF-8 cho Unicode. Nếu những thiết lập này không phù hợp với bạn thì có thể thay đổi sử dụng công cụ thiết lập đi kèm với ibus-bogo.

Để mở công cụ này thì bạn có thể tìm kiếm từ BoGo trong mục tìm kiếm phần mềm (Dash Launcher, GNOME Do...) hoặc tìm trong menu Applications/Utility.

_images/launch_bogo_settings.png

Hoặc nếu ibus-bogo đang chạy thì bạn có thể nhấn nút Preferences hình hộp dụng cụ trên menu của IBus.

_images/ibus_menu.png

Sau đó chương trình sẽ hiện ra với giao diện như sau:

_images/settings.png

Gõ lẫn tiếng Anh trong văn bản tiếng Việt

ibus-bogo đi kèm tính năng nhận dạng từ không đúng chính tả tiếng Việt (chẳng hạn như thuật ngữ tiếng Anh) và tự động chuyển từ đang gõ dở thành tập hợp phím đã gõ:

_images/skip_non_vietnamese.gif

Gõ tắt

Tính năng này đã được thêm vào từ bản 0.4. Bạn cần tạo luật gõ tắt (hoặc import từ Unikey) và bật tùy chọn cho phép gõ tắt:

_images/text_expansion.png

BoGo còn có thể tự động viết hoa cụm gõ tắt giúp bạn. Rất tiện khi gõ ở tiêu đề văn bản.

_images/auto_capitalize.gif

Chuyển đổi bảng mã trong clipboard

Từ bản 0.3 thì ibus-bogo đã có thể chuyển đổi văn bản trong clipboard từ các bảng mã cũ như TCVN3, VNI sang Unicode (dạng UTF-8).

_images/converter.png

Bạn cần copy một đoạn văn bản, chọn bảng mã nguồn và nhấn nút Chuyển đổi, sau đó dán trở lại chỗ cũ.

Note

Tính năng này có một số hạn chế hiện tại như chỉ hỗ trợ bảng mã nguồn là TCVN3 và VNI, chỉ hỗ trợ bảng mã đích là UTF-8. Hiện tại cũng chưa đủ thông minh để phân tích dữ liệu XML trong clipboard của LibreOffice. Mọi ý kiến đóng góp luôn được hoan nghênh.

Tham gia phát triển

Mã nguồn ibus-bogo được đặt trên Github ở địa chỉ: https://github.com/BoGoEngine/ibus-bogo-python

Để tham gia viết code bạn cần biết cách sử dụng git và lập trình bằng python.

Hãy fork và tạo một branch mới từ branch develop (xem phần Git Flow bên dưới), sau đó viết code và gửi chúng tôi một pull request. Chúng tôi sẽ xem xét và commit code của bạn trong thời gian sớm nhất.

Tuy nhiên, bạn cũng có thể đóng góp theo những cách đơn giản hơn như sử dụng phiên bản unstable và thông báo lỗi, viết hướng dẫn sử dụng, viết blog, chia sẻ với bạn bè và người thân về bộ gõ tiếng Việt này.

Hãy trò chuyện với chúng tôi thông qua IRC ở kênh #bogo trên mạng Freenode nếu bạn có mong muốn giúp sức. Mọi sự đóng góp của các bạn dù dưới hình thức nào cũng đều được chúng tôi hết sức trân trọng.

Cấu trúc code

Chúng tôi cố gắng module hóa phần mềm để dễ dàng chuyển sang các nền tảng khác nên BoGo được chia làm 2 thành phần là IBus engine và BoGo engine. BoGo engine là phần xử lý tiếng Việt chính nằm trong thư mục /bogo có API đơn giản (hàm process_key()). Còn IBus engine là phần giao tiếp với IBus, gồm tất cả các file và thư mục con trong /ibus_engine có nhiệm vụ gọi hàm process_key, đưa kết quả cho người dùng và tạo giao diện tinh chỉnh phương pháp gõ.

Coding style

Chúng tôi sử dụng flake8 để thực hiện kiểm tra styling và những lỗi cơ bản. Hãy đảm bảo code của bạn vượt qua được flake8 trước khi tạo pull request.

Documentation

Chúng tôi cũng cố gắng viết code thật dễ hiểu với documentation, comment đầy đủ trong code nên hi vọng bạn sẽ không cảm thấy khó khăn khi tìm hiểu BoGo.

Thành phần IBus engine có sử dụng các thư viện ngoài của IBus, Gtk và GLib/GIO. Bạn có thể tìm thấy tài liệu về cách sử dụng chúng dưới đây:

Testing

Nhóm phát triển ibus-bogo sử dụng phương pháp TDD (test-driven development) để phát triển phần mềm. Khi đóng góp cho BoGo, bạn luôn phải viết test mỗi khi thay đổi code. Các test case có thể tìm thấy trong thư con mục test nằm trong mỗi thư mục lớn của dự án.

Để chạy test, bạn cần cài nosetests cho Python 3 và chạy lệnh sau ở thư mục ngoài cùng:

nosetests

Nosetests sẽ tự tìm, chạy tất cả các test và in kết quả ra màn hình.

Note

Lệnh trên sẽ chạy tất cả các test trong dự án (khoảng 37000 test) nên tốn khoảng 2 đến 3 phút mới chạy xong. Bạn có thể skip các test được đánh dấu là chạy chậm bằng lệnh sau:

nosetests --attr "!slow"

Git Flow

ibus-bogo được quản lý bằng Git. Phương pháp này sử dụng có thể trình bày sơ lược như sau:

  • Repo chính trên Github luôn có 2 branch là masterdevelop. master luôn chứa phiên bản stable mới nhất còn develop là branch chứa tất cả những thay đổi mới nhất của BoGo. Tuy nhiên, thường ít khi commit trực tiếp vào develop ngoài những commit sửa lỗi nhỏ.
  • Khi thực hiện một tính năng mới thì lập trình viên tạo branch mới với tên feature/<tên tính năng>. Khi đã cảm thấy đủ chín thì merge branch này với develop và xóa branch feature/* đi. Từ sau trở đi tính năng này sẽ được maintain trong branch develop.
  • Khi có đủ tính năng mới và các lỗi quan trọng đã được sửa thì có thể tính đến việc release phiên bản major mới. Khi đó tạo branch release/v<phiên bản> và thực hiện tất cả các commit sửa lỗi cho phiên bản này tại đây. Khi tất cả các lỗi trước khi phát hành được sửa hết thì sửa version string trong source code, tạo tag cho phiên bản mới và merge vào master. Trong toàn bộ quá trình này, các thay đổi mới vẫn thực hiện ở các feature branch và develop như bình thường. Sau khi release thì các commit ở release/* được merge trở lại vào develop.
  • Sau khi release phiên bản major mà phát hiện lỗi đặc biệt nghiêm trọng nào đó thì phải sửa ngay lập tức và release phiên bản minor với branch hotfix/v<phiên bản>. Quy trình giống như một branch release/*. Sau khi release phải merge lại vào develop.
Chi tiết về phương pháp git flow:
http://nvie.com/posts/a-successful-git-branching-model/
Công cụ hỗ trợ git-flow:
http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/

Giấy phép xuất bản (License)

ibus-bogophần mềm tự do nguồn mở.

Toàn bộ mã nguồn của ibus-bogoBoGo cùng tất cả các tài nguyên đi kèm đều được phát hành dưới các quy định ghi trong Giấy phép Công cộng GNU, phiên bản 3.0 (GNU General Public License v3.0).

Ghi công (Credits)

Bản quyền thuộc về các tác giả nằm trong file AUTHORS với thời hạn ghi trong phần LICENSE của từng file mã nguồn.

Indices and tables