Bug 1449

Summary: Update GlueGen Documentation
Product: [JogAmp] Gluegen Reporter: Sven Gothel <sgothel>
Component: coreAssignee: Sven Gothel <sgothel>
Status: RESOLVED FIXED    
Severity: normal CC: mfery
Priority: P4    
Version: 2.5.0   
Hardware: All   
OS: all   
Type: DEFECT SCM Refs:
9b825a445c3d2646546306c1815f498406e2f8c3 fd623305d90a88fd01dea3dccf6b9fe76b19703f 9250960f107cebbb4e6d3a55009b330f101453ea 8850b3d7f82ca5f1f828192407574581abd82ef9
Workaround: ---
Bug Depends on:    
Bug Blocks: 1451    

Description Sven Gothel 2023-08-09 15:18:02 CEST
Synchronize GlueGen documentation with current code, i.e. latest code changes as well as some of the JOGL_2_SANDBOX efforts back then.

I started producing a new document as of late covering these matters
- https://jogamp.org/cgit/gluegen.git/tree/doc/GlueGen_Mapping.md

Perhaps we want to make a choice to at least update 
the GlueGen config options in 
https://jogamp.org/gluegen/doc/manual/

I personally prefer using Markdown document format over the html one.
Perhaps we can convert the html version automatically to markdown
and then merge to document?
Comment 1 Mathieu Féry (MathiusD) 2023-08-10 12:17:07 CEST
Yes, synchronizing the manual is necessary, especially for the configuration options.

I also prefer the markdown format, which allows you to concentrate on the content rather than the form imho.

I'm putting all the documentation I've made on a branch by the end of the day or tomorrow at the latest.
Comment 2 Mathieu Féry (MathiusD) 2023-08-13 23:33:16 CEST
Sorry for the delay, it's been a busy week :x, but here's a partial update of the manual I placed on this branch: 1449-manual-sync-configuration-entries of my branch (https://github.com/MathiusD/gluegen as always)
Comment 3 Sven Gothel 2023-08-14 02:33:20 CEST
Merged index.html change 9b825a445c3d2646546306c1815f498406e2f8c3
of comment 2.

Thank you Mathieu!
Comment 4 Sven Gothel 2023-08-14 04:30:56 CEST
commit fd623305d90a88fd01dea3dccf6b9fe76b19703f

Convert manual/index.html to `gfm` (GitHub-Flavored Markdown) using markdown 
-> manual/index.md 

also adds conversion recipes + make/scripts/md2html_update.sh
    
    Note: Additionally edited 'doc/misc/macos_nativelib_dependencies.md`
    to include `Use explicit OpenJDK/Temurin JDK `java` executable path`
    as a workaround to pass `DYLD_LIBRARY_PATH` to `/usr/bin/java`.

+++

Conversion was done using:

  pandoc index.html -t gfm -o index.md
Comment 5 Sven Gothel 2023-08-14 04:32:08 CEST
(In reply to Sven Gothel from comment #4)

We convert markdown using pandoc using `gfm` (GitHub-Flavored Markdown) as source format
and `html5+smart` with a custom template as the target.

Recipe:
```
  ~/pandoc-buttondown-cgit/pandoc_md2html_local.sh GlueGen_Mapping.md > GlueGen_Mapping.html
```  

Git repos:
- https://jausoft.com/cgit/users/sgothel/pandoc-buttondown-cgit.git/about/
- https://github.com/sgothel/pandoc-buttondown-cgit
Comment 6 Sven Gothel 2023-08-14 04:43:21 CEST
Closing this portion of GlueGen documentation updates for 2.5.0, 
further work will be done under Bug 1451