Page MenuHomeFreeBSD

fix asciidoc code in listing blocks in fdp-primer
Needs ReviewPublic

Authored by vladlen on Sun, Sep 28, 11:32 AM.
Tags
Referenced Files
F133580868: D52774.id.diff
Sun, Oct 26, 7:31 PM
Unknown Object (File)
Sat, Oct 25, 4:01 PM
Unknown Object (File)
Sat, Oct 25, 5:07 AM
Unknown Object (File)
Fri, Oct 24, 2:22 PM
Unknown Object (File)
Thu, Oct 23, 12:02 AM
Restricted File
Wed, Oct 15, 11:02 AM
Unknown Object (File)
Tue, Oct 14, 3:17 PM
Unknown Object (File)
Tue, Oct 14, 3:17 PM
Subscribers

Details

Reviewers
maxim
Group Reviewers
doceng
Summary

FDP-primer has many examples of AsciiDoc code , that are placed into files in AsciiDoc format. It is always tricky to correctly represent AsciiDoc using AsciiDoc.

Known problems:

  1. some of commands (like include::, ifdef::) executed instead of rendering to text, creating wrong output in the original version of the document
  2. additionally some commands (like include::, ifdef::, all lines started from - and = interpreted as headers) break the work of po4a, that consider the remaining part of code block as usual text, and PO file for translation contain data, that cannot be processed on later steps and require manual correction (in fdp-primer - examples, asciidoc-primer).

Solution:

I propose simple solution: all lines in the code blocks containing AsciiDoc code as example must be prepended by space char. It is not visible, samples of code are rendered fine.

The same technique already used in developers-handbool/kerneldebug chapter - all debugger commands have prepended space char, it works good in original output and in Weblate.

This problem affects mainly these 4 files in FDP-primer. All other documentation has only 2 cases, when example code included line '---' as divider of the code, that is interpreted as AsciiDoc directive.

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

vladlen created this revision.

I think it's ok but we need to document it in the FDP

I added the note after first appearance of the AsciiDoc code in AsciiDoc primer. It look like this image.{F132277855}