ya_multilingual_markdown 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 461ba09dd9d70bb8fdc0c7faf1ec95c34ad28a608eac30cd5c6eb1f7e039e7aa
-  data.tar.gz: 5312109dee3c9600782046f26e72dd73c08bdfbde3e73cba88a7b3d13c8563fe
+  metadata.gz: 85b65af64f47695df849bc48706b3fe3b2f691cbb7205d9edd9dbdaf7627bbee
+  data.tar.gz: 0d95434a2e33c236b7736b2825b31f774db3249cc2c14b70f8b5caf011699b6b
 SHA512:
-  metadata.gz: a39a6be3c2f75f93b65833d9f9dee104a6c663a80cfc6b7914be62e5456bf70aa75f23c23f1bb946e578595387ba7b199aab4ec3ba9d8b17adbdb9f52b423881
-  data.tar.gz: a55008caa80072df3b578bb075d5667340d936f1f7b3589a51ec3afbd747d6ef026d8561d746efad94fa88bb7e560f9b091ef0cb9cf51a38c6c7032c7ee46bf9
+  metadata.gz: 640cdf404f1ecead1e4483816e7fb0adee0c233479ccb02567c69eaf0cc9c9ebc1b64e7250a3e102609d0d096f874c0862c4d5ec7b50c913f3bc0df7120acae9
+  data.tar.gz: 24bae476fa264efdd35258ea493b4b583410d2f5ca227105a4ed867f324fad481bc7efed73e869af31d76f339df3e4288eb9d713847a0cd259f1dddc644f5f5c

data/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+# see https://github.com/ruby/setup-ruby
+
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby: ["3.3", "3.4"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rake

data/.rubocop.yml

@@ -0,0 +1,2 @@
+inherit_gem:
+  rubocop-shopify: rubocop.yml

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright and condition of use of main portion of the source:
+
+----
+
+Copyright 2020 Hisashi Morita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+----
+
+Copyright of kramdown's parse_emphasis, from which parse_ml_emphasis derived:
+
+Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+This file is part of kramdown which is licensed under the MIT.

data/README.md

@@ -0,0 +1,352 @@
+# YAMultilingualMarkdown
+
+  * English / [Japanese](README_ja.md)
+
+YAMultilingualMarkdown is a utility to convert Yet Another Multilingual Markdown to HTML and other formats.
+
+Yet Another Multilingual Markdown (format) is a Markdown dialect designed for hosting multilingual content. YAMultilingualMarkdown (tool) converts Yet Another Multilingual Markdown to other formats while extracting only the content in specified language(s).
+
+## Usage
+
+### Synopsis
+
+```shell
+ya_multilingual_markdown [OPTIONS] [FILE]
+```
+
+### Options
+
+Type `ya_multilingual_markdown --help` to show command line options.
+
+```
+Convert Yet Another Multilingual Markdown to HTML and other formats
+
+Usage:
+  ya_multilingual_markdown [OPTIONS] [FILE]
+
+Options:
+        --output-format=FORMAT       Output format
+                                     (html|kramdown|markdown)
+                                     (default: html)
+        --langs=LANG1,LANG2,...      Languages to be included
+                                     (omitting this option implies all)
+        --heading-lang-sep=STRING    Languages separator in headings
+                                     (default: " / ")
+        --lang-attr-name=STRING      Attribute name for language
+                                     (default: lang)
+        --html-output-type=TYPE      Output type for HTML output
+                                     (fragment|document)
+                                     (default: fragment)
+        --html-template-file=FILE    HTML document template file in eRuby format
+        --html-link-suffixes=FROM:TO,...
+                                     Link suffixes to rewrite in HTML output
+                                     (default: .md:.html)
+        --show-default-html-template Show default HTML document template
+        --log-level=SEVERITY         Log level
+                                     (unknown|fatal|error|warn|info|debug)
+                                     (default: warn)
+        --help                       Show help message
+        --version                    Show version
+```
+
+## Examples
+
+### Multilingual contents: headings, paragraphs, and other elements
+
+A simple Yet Aonther Multilingual Markdown document looks like the following (`snow_white.md`):
+
+```markdown
+# Schneeweißchen
+{: lang="de"}
+
+# Little Snow-white
+{: lang="en"}
+
+Es war einmal mitten im Winter,...
+{: lang="de"}
+
+Once upon a time in the middle of winter,...
+{: lang="en"}
+```
+
+(You can use kramdown-style (PHP Markdown Extra-style) extended syntax (`{: name="value"}`) to add attributes to block elements.)
+
+#### Keep all languages
+
+Without language-related options, the output will contain all languages.
+
+```shell
+ya_multilingual_markdown snow_white.md
+```
+
+Excerpt from the output:
+
+```html
+<h1><span lang="de">Schneeweißchen</span> / <span lang="en">Little Snow-white</span></h1>
+
+<p lang="de">Es war einmal mitten im Winter,...</p>
+
+<p lang="en">Once upon a time in the middle of winter,...</p>
+```
+
+In a browser, above output may look like the following:
+
+> **Schneeweißchen / Little Snow-white**
+>
+> Es war einmal mitten im Winter, ...
+>
+> Once upon a time in the middle of winter, ...
+
+#### Extract single language
+
+With option `--langs=en`, the output will contain only the elements with `lang` whose value is set to `en` (and elements without `lang` attribute).
+
+```shell
+ya_multilingual_markdown --langs=en snow_white.md
+```
+
+Excerpt from the output:
+
+```html
+<h1><span lang="en">Little Snow-white</span></h1>
+
+
+<p lang="en">Once upon a time in the middle of winter, ...</p>
+```
+
+In a browser, above output may look like the following:
+
+> **Little Snow-white**
+>
+> Once upon a time in the middle of winter, ...
+
+#### Extract multiple languages
+
+With option `--langs=de,en`, the output will contain elements with `lang` set to `de` or `en` (and elements without `lang`).
+
+```shell
+ya_multilingual_markdown --langs=de,en snow_white.md
+```
+
+Excerpt from the output:
+
+```html
+<h1><span lang="de">Schneeweißchen</span> / <span lang="en">Little Snow-white</span></h1>
+
+<p lang="de">Es war einmal mitten im Winter,...</p>
+
+<p lang="en">Once upon a time in the middle of winter,...</p>
+```
+
+In a browser, the output may look like the following:
+
+> **Schneeweißchen / Little Snow-white**
+>
+> Es war einmal mitten im Winter, ...
+>
+> Once upon a time in the middle of winter, ...
+
+### Metadata in YAML front matter
+
+Document metadata can be stored in the document using Jekyll-style YAML front matter.
+
+A simple Yet Aonther Multilingual Markdown document with YAML front matter looks like the following (`snow_white_with_metadata.md`):
+
+```
+---
+title: Little Snow-white
+author:
+  - Jacob Ludwig Karl Grimm
+  - Wilhelm Carl Grimm
+meta:
+  - name: original title
+    content: Schneeweißchen
+    lang: de
+  - name: translator
+    content: Margaret Hunt
+    lang: en
+---
+...
+```
+
+(The key `author` is a shortcut to `<meta name="author" .../>`.)
+
+Let us include all languages in the output:
+
+```shell
+ya_multilingual_markdown snow_white_with_metadata.md
+```
+
+Excerpt from the output:
+
+```html
+<title>Little Snow-white</title>
+<meta name="author" content="Jacob Ludwig Karl Grimm" />
+<meta name="author" content="Wilhelm Carl Grimm" />
+<meta name="original title" content="Schneeweißchen" lang="de" />
+<meta name="translator" content="Margaret Hunt" lang="en" />
+<p>...</p>
+```
+
+You can filter metadata based on their languages.
+
+Let us include `en` only (thus exclude `de`) in the output:
+
+```shell
+ya_multilingual_markdown --langs=en snow_white_with_metadata.md
+```
+
+Excerpt from the output:
+
+```html
+<title>Little Snow-white</title>
+<meta name="author" content="Jacob Ludwig Karl Grimm" />
+<meta name="author" content="Wilhelm Carl Grimm" />
+<meta name="translator" content="Margaret Hunt" lang="en" />
+<p>...</p>
+```
+
+### Output complete HTML document
+
+Use `--html-output-type=document` to print complete HTML document rather than HTML fragments.
+
+Input:
+
+```
+---
+title: Little Snow-white
+---
+Once upon a time in the middle of winter, ...
+```
+
+Command line:
+
+```shell
+ya_multilingual_markdown --html-output-type=document snow_white_with_title.md
+```
+
+Output:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Little Snow-white</title>
+  </head>
+  <body>
+    <p>Once upon a time in the middle of winter, ...</p>
+  </body>
+</html>
+```
+
+You can provide a custom template using `--html-template-file=FILE`. Templates must be in [eRuby](https://docs.ruby-lang.org/en/master/ERB.html) format. Use `--show-default-html-template` to see the built-in default template.
+
+## Installation
+
+```
+gem install ya_multilingual_markdown
+```
+
+or
+
+```
+git clone https://github.com/hisashim/ya_multilingual_markdown
+cd ya_multilingual_markdown
+rake install
+```
+
+## Requirements
+
+Runtime requirements:
+
+  * [Ruby](https://www.ruby-lang.org/)
+  * [kramdown](https://kramdown.gettalong.org/)
+    - [Rouge](https://github.com/rouge-ruby/rouge/)
+  * [kramdown-parser-gfm](https://github.com/kramdown/parser-gfm/)
+  * [kramdown-math-katex](https://github.com/kramdown/math-katex/)
+
+Development requirements (in addition to runtime requirements):
+
+  * [Rake](https://ruby.github.io/rake/)
+  * [Bundler](https://bundler.io/)
+  * [Minitest](https://github.com/minitest/minitest)
+  * [Rubocop](https://github.com/rubocop/rubocop) (optional)
+    - [Shopify's Ruby Style Guide](https://github.com/Shopify/ruby-style-guide)
+
+## Notes
+
+### Limitations and known problems
+
+  * Only a small subset of kramdown's extended syntax is supported, although YAMultilingualMarkdown is built upon kramdown.
+
+  * As for multilingual headings, ALD (Attribute List Definition) for each heading must be placed only _after_ the heading.
+
+    Supported:
+    ```
+    # Schneeweißchen
+    {: lang="de"}
+
+    # Little Snow-white
+    {: lang="en"}
+    ```
+
+    Not supported:
+    ```
+    {: lang="de"}
+    # Schneeweißchen
+
+    {: lang="en"}
+    # Little Snow-white
+    ```
+
+    This compromise allows us to write id at the beginning of headings as well as at the end, with less code.
+
+    ```
+    {: #title}
+    # Schneeweißchen
+    {: lang="de"}
+
+    # Little Snow-white
+    {: lang="en"}
+    ```
+
+    ```
+    # Schneeweißchen
+    {: lang="de"}
+
+    # Little Snow-white
+    {: lang="en"}
+    {: #title}
+    ```
+
+### Motivation
+
+Yet Aonther Multilingual Markdown and its processor were born out of the need for a manuscript format for translated books.
+
+Having a side-by-side version of the galley proof that includes both the original and translated texts helps translators review their work. Being able to search and edit manuscripts in a (sort of) side-by-side format is also useful.
+
+While placing translated text in separate files from the original is a common and effective approach for localization/multilingualization projects, a format allowing multiple languages within a single file comes in handy for small projects. Yet Aonther Multilingual Markdown is an attempt to develop a proof of concept for such a format and a processing tool.
+
+### See also
+
+  * [Requirements for Japanese Text Layout](https://w3c.github.io/jlreq/) is an excellent example of a multilingual document in HTML format.
+
+  * Lightweight text formats and processing tools that allow multiple languages to be written in a single file (not necessarily feature or aim at extracting or representing multiple languages side-by-side):
+    - [Multilang Preprocessor](https://github.com/polm/multilang-filter)
+    - [greple](https://github.com/kaz-utashiro/greple)
+    - [Multilingual Markdown Generator](https://mmg.ryul1206.dev/)
+
+## License
+
+This software is distributed under the terms of the [MIT license](LICENSE).
+
+## Acknowledgments
+
+Many thanks to:
+
+  * Koichi Sasada, whose manuscript preprocessor inspired me to come up with a lightweight markup format that features multilingualization.
+  * kramdown developers
+
+## Contributors
+
+  * [Hisashi Morita](https://github.com/hisashim) - creator and maintainer