defensive-coding-guide

Clone
Source Code
GIT

#7 Not buildable by Antora
Closed: Fixed 2 years ago by pbokoc. Opened 4 years ago by mjahoda.

Closed: Fixed
Reopen Issue

The majority of source files must be updated to be compatible with Antora:

asciidoctor: ERROR: C-Language.adoc: line 59: include target not found: ../snippets/C-Pointers-remaining.adoc
asciidoctor: ERROR: C-Language.adoc: line 89: include target not found: ../snippets/C-Arithmetic-add.adoc
asciidoctor: ERROR: C-Language.adoc: line 116: include target not found: ../snippets/C-Arithmetic-add_unsigned.adoc
asciidoctor: ERROR: C-Language.adoc: line 132: include target not found: ../snippets/C-Arithmetic-mult.adoc
asciidoctor: ERROR: C-Language.adoc: line 192: include target not found: ../snippets/C-Globals-String_Array.adoc
asciidoctor: ERROR: C-Libc.adoc: line 130: include target not found: ../snippets/C-String-Functions-snprintf.adoc
asciidoctor: ERROR: C-Libc.adoc: line 160: include target not found: ../snippets/C-String-Functions-snprintf-incremental.adoc
asciidoctor: ERROR: C-Libc.adoc: line 195: include target not found: ../snippets/C-String-Functions-format.adoc
asciidoctor: ERROR: C-Libc.adoc: line 210: include target not found: ../snippets/C-String-Functions-strncpy.adoc
asciidoctor: ERROR: C-Libc.adoc: line 219: include target not found: ../snippets/C-String-Functions-strncat-as-strncpy.adoc
asciidoctor: ERROR: C-Libc.adoc: line 242: include target not found: ../snippets/C-String-Functions-strncat-emulation.adoc
asciidoctor: ERROR: C-Libc.adoc: line 252: include target not found: ../snippets/C-String-Functions-strncat-merged.adoc
asciidoctor: ERROR: C.adoc: line 7: include target not found: en-US/programming-languages/C-Language.adoc
asciidoctor: ERROR: C.adoc: line 9: include target not found: en-US/programming-languages/C-Libc.adoc
asciidoctor: ERROR: C.adoc: line 11: include target not found: en-US/programming-languages/C-Allocators.adoc
asciidoctor: ERROR: C.adoc: line 13: include target not found: en-US/programming-languages/C-Other.adoc
asciidoctor: ERROR: CXX.adoc: line 6: include target not found: en-US/programming-languages/CXX-Language.adoc
asciidoctor: ERROR: CXX.adoc: line 8: include target not found: en-US/programming-languages/CXX-Std.adoc
asciidoctor: ERROR: Go.adoc: line 56: include target not found: ../snippets/Go-Error_Handling-Regular.adoc
asciidoctor: ERROR: Go.adoc: line 76: include target not found: ../snippets/Go-Error_Handling-IO.adoc
asciidoctor: ERROR: Java-Language.adoc: line 34: include target not found: ../snippets/Java-Language-ReadArray.adoc
asciidoctor: ERROR: Java-Language.adoc: line 65: include target not found: ../snippets/Java-Finally.adoc
asciidoctor: ERROR: Java-Language.adoc: line 90: include target not found: ../snippets/Java-TryWithResource.adoc
asciidoctor: ERROR: Java-LowLevel.adoc: line 78: include target not found: ../snippets/Java-JNI-Pointers.adoc
asciidoctor: ERROR: Java-SecurityManager.adoc: line 113: include target not found: ../snippets/Java-SecurityManager-Unprivileged.adoc
asciidoctor: ERROR: Java-SecurityManager.adoc: line 126: include target not found: ../snippets/Java-SecurityManager-CurrentDirectory.adoc
asciidoctor: ERROR: Java-SecurityManager.adoc: line 211: include target not found: ../snippets/Java-SecurityManager-Privileged.adoc
asciidoctor: ERROR: Java-SecurityManager.adoc: line 252: include target not found: ../snippets/Java-SecurityManager-Callback.adoc
asciidoctor: ERROR: Java.adoc: line 7: include target not found: en-US/programming-languages/Java-Language.adoc
asciidoctor: ERROR: Java.adoc: line 9: include target not found: en-US/programming-languages/Java-LowLevel.adoc
asciidoctor: ERROR: Java.adoc: line 11: include target not found: en-US/programming-languages/Java-SecurityManager.adoc
asciidoctor: ERROR: Shell.adoc: line 353: include target not found: ../snippets/Shell-Input_Validation.adoc

Alright, I fixed all the errors, that was the easy part, it's already on master. However the book still isn't in a properly buildable state, and it will require reorganizing. I'll keep this issue open and track it here. This is what will need doing:

  • We'll need to fix all xrefs because the current ones expect the whole guide to be a tree. We'll need to use Antora's page ID syntax instead to identify the xref target, not just the ASCIIDoc ID that's currently being used.
  • We should also update the structure. Currently, the pages for C, C++, and Java are split into several submodules, and there's no reason in Antora to do this. We could treat each of these current submodules as separate pages; this means:
    • Fixing the titles (each page must have a 1st level title, the subpages start at level 2 I think that's what currently causes them to break completely). This means not just the top heading, all titles need to be adjusted one level up.
    • Unincluding the subpages from the main page.
    • Adding some basic content on each current main page (e.g. C.adoc) because they're empty right now except for the includes.
    • Updating the navfile so it links to each subpage.
  • Additionally, it would be best if we put the examples where they belong; this will require an update to the python script that generates them. Instead of going into modules/ROOT/pages/_partials/, the examples should go into modules/ROOT/examples/, and they should be included using include::example$filename.extension. It's possible that including them as adoc files also causes some of the current breakages, so we might have no choice but to do this too.
Edited 4 years ago by pbokoc

@pbokoc Thank you for working on this.

I am adding @adelton and @nmav to the loop.

The guide is now all cleaned up, builds without errors, all xrefs work, and the structure and build scripts are both updated to current versions.

Metadata Update from @pbokoc:
- Issue close_status updated to: Fixed
- Issue status updated to: Closed (was: Open)
2 years ago

Log in to comment on this ticket.

Metadata
None
None
None
Powered by Pagure 5.14.1
Documentation • File an Issue • About • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.