Xuất bản Hướng dẫn dành cho nhà phát triển Asciidoc của chúng tôi dưới dạng sách trên Amazon

Tôi nghĩ xuất bản trên máy tính để bàn là một “vấn đề đã được giải quyết” nhưng có vẻ như nó còn khá xa. Khi tôi làm việc cho Sun Microsystems, nhà văn công nghệ của chúng tôi sẽ chỉ soạn tài liệu cuối cùng từ công việc của chúng tôi một cách “kỳ diệu”. Khi tôi làm việc cho các công ty khác, chúng tôi chủ yếu viết tài liệu nội bộ và sử dụng Word. Tuy nhiên, với Codename One, tôi đã phải chọn tất cả những điều đó và tôi đã học được những điều tồi tệ như thế nào trong thế giới thực.

Trong bài viết này, tôi muốn mô tả chuỗi công cụ của chúng tôi, các bài học kinh nghiệm và cách chúng tôi tạo tài liệu của mình như một dự án mã nguồn mở lớn, được ghi chép nhiều. Có rất nhiều hướng dẫn và tài nguyên về asciidoc, đây không phải là một trong số đó. Nếu bạn quan tâm đến asciidoc, O'Reilly đã làm một bài hướng dẫn tuyệt vời về điều đó . Tôi sẽ đưa ra một số mẹo ở phần cuối dựa trên kinh nghiệm của tôi với asciidoc, nhưng tôi chủ yếu viết bài này để giúp các dự án khác quyết định xem họ nên sử dụng asciidoc hay bám vào chuỗi công cụ tài liệu hiện có của họ.

Tại sao Asciidoc?

Ban đầu, tôi làm việc với Open Office và Word. Cả hai đều OK với tư cách là người chỉnh sửa văn bản và tôi đã quen với việc làm việc với họ nhưng đến lúc phải làm những việc như tô sáng mã hoặc công việc cộng tác, họ trở thành một nỗi đau. Tôi cũng phát hiện ra rằng bạn cần biết mình đang làm gì để tạo ra một tài liệu đẹp từ một trong hai tài liệu đó. Chúng khiến bạn rất dễ viết “xấu” mà không có kiểu dáng và điều đó khiến bạn rất khó tạo ra một tài liệu thống nhất phù hợp.

Tôi thích bản chất trực quan của việc chỉnh sửa nhưng tôi không thực sự cần nó. Tính năng yêu thích của tôi có lẽ là trình kiểm tra ngữ pháp sai nhiều trong Word… Vâng, tôi biết “nó tệ” nhưng ngữ pháp của tôi cũng vậy.

Kết quả cuối cùng trông thật tệ hại và thực sự khó duy trì. Tôi cũng muốn nhiều hơn:

• Tôi muốn có một bản PDF đẹp.
• Tôi muốn hướng dẫn tích hợp vào trang web của chúng tôi.

Chúng tôi cũng đã thử sử dụng Google Documents một thời gian nhưng chúng tôi gặp vấn đề trong việc mở rộng quy mô và phát triển khía cạnh cộng tác. Khi cộng đồng có thể chỉnh sửa tài liệu, họ có thể phá vỡ định dạng và điều đó thực sự khó theo dõi. Kết quả của Google Documents thậm chí còn tệ hơn Word nên đó cũng không phải là một lựa chọn tốt.

Nhập JBake

Chúng tôi bắt đầu sử dụng JBake cho trang web của mình sau khi thử nhiều trình tạo trang tĩnh khác. Nó hoạt động thực sự tốt và chúng tôi yêu thích ý tưởng tạo trang web tĩnh cho các phần tử chung. Một trong những tính năng tuyệt vời trong JBake là hỗ trợ Asciidoc và sau khi chúng tôi xem xét tất cả các tùy chọn khác, có vẻ như đây sẽ là cách “hợp lý” duy nhất để có một hướng dẫn mà chúng tôi có thể tạo cả dưới dạng PDF và HTML trông đẹp mắt.

Bên cạnh tất cả những điều đó, Asciidoc có một số lợi thế đáng chú ý so với các bộ xử lý văn bản:

• Làm nổi bật mã nguồn tích hợp.
• Dựa trên văn bản để chúng tôi có thể tự động hóa một số phần của chuỗi công cụ.
• Trông đẹp theo mặc định.
• Có thể được sử dụng trong các trang wiki của GitHub và được hiểu bởi GitHub nói chung.
• Được sử dụng bởi các nhà xuất bản lớn như O'Reilly.

Chúng tôi cũng đã nghĩ về markdown nhưng cuối cùng đã đi với asciidoc, có vẻ như hướng đến xuất bản trên máy tính để bàn trong khi markdown hướng đến đầu ra web hơn.

Điều thú vị về asciidoc là nó thực tế được xây dựng với các lập trình viên. Những thứ như “chú thích” cho phép bạn đặt các số trong mã và sau đó giải thích chúng sau khi mã là điều tầm thường trong asciidoc nhưng lại gây khó khăn với khá nhiều công cụ khác mà tôi đã sử dụng.

Quá trình của chúng tôi

Vì chúng tôi muốn mọi thứ được chia nhỏ và có thể quản lý, chúng tôi đã đặt mọi phân đoạn trong một tệp asciidoc riêng biệt và lưu trữ chúng trong wiki GitHub của chúng tôi . Điều này cho phép hầu hết mọi người chỉ cần chỉnh sửa tệp và cũng cung cấp cho chúng tôi lịch sử tuyệt vời về các thay đổi đối với tệp.

Sau đó, chúng tôi cần tạo các tệp JBake cho trang web, tệp này sẽ bao gồm các tiêu đề tùy chỉnh cho điều đó. Tôi đã tạo một tập lệnh shell đơn giản chỉ sao chép các tệp từ wiki vào nền tảng web JBake của chúng tôi. Nó hơi dài nhưng nhìn chung, nó trông giống như thế này (lặp lại cho mỗi tệp):

echo "title=About The Codename One Developer Guide - Build Cross Platform Apps Using Java
type=manual
tags=docs
status=published
previousPage=gui-builder
nextPage=introduction
~~~~~~
:icons: font
" | cat - ~/dev/CodenameOne.wiki/About-This-Guide.asciidoc | sed "s/image::/image::\//g" | sed "s/image:img/image:\/img/g" > ~/dev/CodenameOne/newWebsite/templates/content/manual/about.adoc 

Nếu bạn không quen với bash, toàn bộ phần trên cùng chỉ là tiêu đề JBake được sử dụng khi chuyển đổi tệp sang HTML tĩnh.

Sau đó, tôi chuyển đầu ra thông qua sed chuyển đổi URI hình ảnh tương đối thành URI hình ảnh tuyệt đối. Logic chính ở đây là thư mục thủ công trong trang web không có trong thư mục gốc và tôi muốn lưu trữ tất cả các hình ảnh ở một nơi. Có một URL tuyệt đối cho phép tôi di chuyển sổ tay sang một vị trí khác một cách dễ dàng. Tuy nhiên, wiki và PDF cần có URL tương đối vì vị trí của hình ảnh khác nhau.

Tôi cũng đặt gợi ý asciidoc để sử dụng phông chữ biểu tượng thay vì hình ảnh khi nó hiển thị ghi chú và các yếu tố khác.

Một tập tin

Một trong những vấn đề / sai lầm lớn mà tôi đã mắc phải khi chúng tôi bắt đầu với asciidoc là quyết định sử dụng một tệp lớn. Một phần của tập lệnh nối tất cả các tệp lại với nhau. Một cách tiếp cận “hiện đại” hơn là việc sử dụng chỉ thị bao gồm từ tệp chính nhưng điều đó đã gây ra một số vấn đề sớm. Thách thức chính là giữ các liên kết theo cách sẽ hoạt động cho cả phiên bản web JBake và cho bản in PDF. Tuy nhiên, cách tiếp cận này hoạt động, vì vậy mặc dù tôi không quá vui mừng với nó, chúng tôi quyết định gắn bó với nó ngay bây giờ.

Chúng tôi đã phải sử dụng các macro đặc biệt mà tập lệnh nối của chúng tôi đã xử lý để liên kết khác với đầu ra PDF và trang web thông thường:

// HTML_ONLY_START
You can learn more about multi-images in the  https://www.codenameone.com/manual/advanced-theming.html#_understanding_images_multi_images[advanced theming] section.
// HTML_ONLY_END
////
//PDF_ONLY
You can learn more about multi-images in the <<understanding-images-and-multi-images>> section.
////

Tập lệnh nối của chúng tôi chỉ là một ứng dụng Java đơn giản nhỏ, chủ yếu là vì tôi viết mã bằng Java dễ dàng hơn bất cứ thứ gì khác. Tôi cũng cần một thứ gì đó phức tạp hơn là chỉ kết nối các tệp với nhau vì tôi muốn có chỉ mục Mục lục trong đầu ra HTML. Để làm điều này, tôi cần một số logic khá dễ thực hiện trong Java (nhờ định dạng tệp văn bản):

public class DevGuideIndexGenerator {
    /**
     * Argument 0 should be the output asciidoc file
     * Argument 1 should be the index file in the website
     * Argument 2 onwards should be the files in the manual in the correct order
     */
    public static void main(String[] args) throws Exception {
        String version = args[0];
        FileOutputStream asciidocFile = new FileOutputStream(args[1]);
        FileWriter indexFile = new FileWriter(args[2]);

        indexFile.write("<div id=\"toc\" class=\"toc2\">\n" +
            "<div id=\"toctitle\">Table of Contents</div>\n" +
            "<ul class=\"sectlevel1\">\n");

        SimpleDateFormat sd = new SimpleDateFormat("MMM dd yyyy");

        asciidocFile.write(("= Codename One Developer Guide\n" +
            "Version " + version + ", " +  sd.format(new Date()) + "\n" +
            ":doctype: book\n" +
            "\n" +
            ":toc:\n" +
            ":toc-placement: manual\n\n" +
            "toc::[]\n\n").getBytes());

        for(int iter = 3 ; iter < args.length ; iter++) {
            File f = new File(args[iter]);
            byte[] currentFile = new byte[(int)f.length()];
            DataInputStream di = new DataInputStream(new FileInputStream(f));
            di.readFully(currentFile);
            di.close();
            String fileContent = new String(currentFile, "UTF-8");
            int index = fileContent.indexOf("~~~~~~");
            String header = fileContent.substring(0, index);
            Properties props = new Properties();
            props.load(new CharArrayReader(header.toCharArray()));
            index = fileContent.indexOf("\n", index);
            fileContent = fileContent.substring(index);

            // remove all the HTML only content
            fileContent = fileContent.replace("// HTML_ONLY_START", "////");
            fileContent = fileContent.replace("// HTML_ONLY_END", "////");

            // comment in "PDF_ONLY" sections
            int pdfOnly = fileContent.indexOf("PDF_ONLY");
            if(pdfOnly > -1) {
                StringBuilder sb = new StringBuilder(fileContent);
                while(pdfOnly > -1) {
                    // replace the block comment following the pdfOnly
                    int followingComment = fileContent.indexOf("////", pdfOnly);
                    sb.setCharAt(followingComment + 2, ' ');
                    sb.setCharAt(followingComment + 3, ' ');
                    int beforeComment = fileContent.lastIndexOf("////", pdfOnly);
                    sb.setCharAt(beforeComment + 2, ' ');
                    sb.setCharAt(beforeComment + 3, ' ');
                    pdfOnly = fileContent.indexOf("PDF_ONLY", followingComment + 2);
                }
                fileContent = sb.toString();
            }

            // first page is the preface
            if(iter == 3) {
                asciidocFile.write("\n[preface]\n== ".getBytes());
            } else {
                asciidocFile.write("\n\n== ".getBytes());
            }
            asciidocFile.write(props.getProperty("title").getBytes());
            if(props.getProperty("subtitle") != null) {
                asciidocFile.write("\n\n".getBytes());                
                asciidocFile.write(props.getProperty("subtitle").getBytes());
            }
            asciidocFile.write(fileContent.replace("image::/img/developer-guide/", "image::").getBytes("UTF-8"));

            String url = f.getName().replace(".adoc", ".html");
            indexFile.write("<li  <#if content.uri?ends_with(\"");
            indexFile.write(url);
            indexFile.write("\")> class=\"current\"</#if> ><a href=\"");
            indexFile.write(url);
            indexFile.write("\">");
            indexFile.write(props.getProperty("title"));
            indexFile.write("</a>\n<ul class=\"sectlevel2\">\n");            

            for(String line : fileContent.split("\n")) {
                if(line.startsWith("=== ")) {
                    line = line.substring(4);
                    indexFile.write("<li><a href=\"");
                    indexFile.write(url);
                    indexFile.write("#");
                    StringTokenizer tt = new StringTokenizer(line.toLowerCase(), " ;&:_");
                    while(tt.hasMoreTokens()) {
                        indexFile.write("_");
                        indexFile.write(tt.nextToken());
                    }
                    indexFile.write("\">");
                    indexFile.write(line);
                    indexFile.write("</a></li>\n");            
                }
            }
            indexFile.write("</ul></li>\n");            
        }
        indexFile.write("</ul></div>\n");

        indexFile.close();
        asciidocFile.close();
    }
}

Lưu ý rằng điều này tương đối đơn giản, chúng tôi chỉ tìm mọi tiêu đề cấp cao nhất và cấp hai dựa trên các quy ước sau đó tạo tệp TOC. Chúng tôi cũng thực hiện tất cả những việc cơ bản như đặt ngày của hướng dẫn dành cho nhà phát triển để mọi thứ được tự động hóa 100% (vâng, tôi biết tôi có thể làm điều đó với một trường trong Word, v.v.).

Macro cho PDF được thực hiện bằng cách chuyển đổi "bình luận ma thuật" chỉ PDF để mã / mô tả hoạt động chính xác trong chế độ PDF.

Ban đầu, chúng tôi sử dụng nó rất nhiều khi thực hiện các liên kết, nhưng gần đây, chúng tôi đã lười biếng vì cú pháp đặc biệt hơi khó khăn.

Liên kết bên ngoài và hình ảnh nổi

Khi viết một trang web, bạn muốn liên kết càng nhiều càng tốt. Vì chúng tôi có JavaDocs rộng rãi, nên tôi nghĩ việc siêu liên kết mọi đề cập đến một lớp đến trang JavaDoc của nó sẽ rất hợp lý. Bên cạnh lợi ích SEO, điều này có thể hữu ích cho các nhà phát triển, những người có thể tìm thấy lớp học ngay lập tức.

Thực hiện điều này trong bộ tiền xử lý không phải là một tùy chọn. Nó sẽ cần một trình phân tích cú pháp phức tạp hơn và tôi không quan tâm đến việc đó. Nhưng tôi đã thực hiện một tập lệnh nhanh để thực hiện điều đó và siêu liên kết mọi thứ sau đó tôi sửa các liên kết xấu theo cách thủ công. Điều này ban đầu có vẻ hiệu quả nhưng có một tác dụng phụ có vấn đề…

Khi chúng tôi tạo tệp PDF, mọi liên kết tạo ra một chú thích cuối trang có ý nghĩa rất nhiều về mặt lý thuyết. Tuy nhiên, trong một trang về Nút , tôi có thể đề cập đến nó 20 lần, điều này sẽ kích hoạt 20 chú thích cuối trang với cùng một URL!

Thật không may, tôi không thể tìm thấy giải pháp cho điều đó vì vậy tôi phải xem qua các liên kết của chúng tôi và cố gắng giảm số lượng. 

Một điều khó chịu khác là hành vi hình ảnh. Bạn có thể dễ dàng thả nổi hình ảnh sang bên phải trong đầu ra HTML nhưng không phải trong đầu ra PDF . Đây có lẽ là vấn đề định dạng khó chịu nhất mà tôi gặp phải. Tôi có thể làm việc xung quanh nó với một số cấu trúc bảng sáng tạo trong một số trường hợp nhưng điều này có vẻ như là một điều tầm thường…

Các vấn đề về chuỗi công cụ

Một trong những vấn đề lớn nhất với asciidoc là nó ở khắp nơi. Có một vài công cụ và một số hoạt động trong khi những công cụ khác tạo ra kết quả "kỳ lạ" hoặc thất bại mà không có lý do thực sự. Gần đây, chúng tôi đã cố gắng tạo tệp epub trực tiếp từ asciidoc thủ công của chúng tôi. Có vẻ như điều này đã dịch tài liệu nội bộ sang docbook không đúng định dạng và sau đó không xác thực được. 
Tôi đoán điều này liên quan đến mã asciidoc nhưng không thể biết tại sao vì định dạng không được xác thực.

Tôi chỉ có thể làm việc với asciidoctor sang HTML và chuỗi công cụ fo-pub. Mọi thứ khác được tạo ra khi lướt qua tài liệu. Có thể có một cảnh báo được in dọc theo đường đi nhưng khi xem qua hàng trăm trang đầu ra, thật khó để nhận thấy cảnh báo. Tôi không chắc một công cụ giống như “lint” sẽ hoạt động cho một cái gì đó như asciidoc vì định dạng quá lỏng lẻo.

Đây không phải là vấn đề lớn, đầu ra docbook của asciidoctor dường như hoạt động tốt và tôi đã có thể sử dụng điều đó sau khi thực tế để tạo ra những thứ như tài liệu epub bằng các công cụ như pandoc . Điều đó khá thú vị vì bạn có thể chuyển đổi đầu ra sang những thứ chẳng hạn như Word tương đối dễ dàng nếu bạn cần gửi nó đi và đầu ra có vẻ tốt.

Đôi khi, tôi phải hack nhiều thứ khác nhau trong fo-pub để làm cho tài liệu trông đẹp hơn, ví dụ như tôi muốn có một hình ảnh bìa đẹp cho cuốn sách mà tôi đã tạo bằng Spark . Vì vậy, để có được hình ảnh này để "che" tệp PDF, tôi đã phải thay đổi asciidoctor-fopub / build / fopub / docbook / fo / split.xsl và thêm các mục nhập cho ảnh bìa:

<xsl:template name="front.cover">
  <xsl:call-template name="page.sequence">
    <xsl:with-param name="master-reference">titlepage-cover-image</xsl:with-param>
    <xsl:with-param name="content">
      <fo:block text-align="center">
     <fo:external-graphic src="developer-guide-cover-image.jpg" content-height="297mm" content-width="210mm"/>
      </fo:block>
    </xsl:with-param>
  </xsl:call-template>
</xsl:template>