Bug 1449

Summary:	Update GlueGen Documentation
Product:	[JogAmp] Gluegen	Reporter:	Sven Gothel <sgothel>
Component:	core	Assignee:	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