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):
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:
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:
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.
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.
Sau đó chương trình sẽ hiện ra với giao diện như sau:
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õ:
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:
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.
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).
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à
master
vàdevelop
.master
luôn chứa phiên bản stable mới nhất còndevelop
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àodevelop
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ớidevelop
và xóa branchfeature/*
đi. Từ sau trở đi tính năng này sẽ được maintain trong branchdevelop
. - 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àodevelop
. - 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 branchrelease/*
. Sau khi release phải merge lại vàodevelop
.
- 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-bogo là phần mềm tự do nguồn mở.
Toàn bộ mã nguồn của ibus-bogo và BoGo 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).