Hi all,
As you know the tutorials are a part of the third donation from Oracle.
I've been doing some exercises on these (just the tutorials, not the
trails):
== New html-convert tool
I've created PR#8 against incubator-netbeans-tools [1]. This contains a
new tool: "html-convert", that processes the third-donation zip file
(once extracted) and:
- Transforms tutorial HTML files to the AsciiDoc format.
- Maintains the same folder structure as in the original donation (cnd,
ide, java, javaee, javame, php, web, webclient, websvc).
- Copies images from the third-donation images directory to a "images"
folder near the tutorials (so it's easier to know which tutorial has
which images). Also warns about missing images.
- Since the directories have no index files in the donation, the tool
creates an index.asciidoc, index_zh_CN.asciidoc, index_ja.asciidoc,
index_pt_BR.asciidoc, index_ca.asciidoc for different languages, and
lists the tutorials on each language, alphabetically sorted).
- Tries to remove the "Contents" section that was manually included in
many tutorials, the proposal is to replace these with an automatically
generated "toc" (Table Of Contents) section (as other parts of the
website have in place).
- Tries to guess appropriate syntax coloring for each source-code excerpt.
- Generates a "external-links.txt" file (72Kb or so) with a list of
external links the tutorials are using. A quick scan of the file shows
we're pointing to many mp4 files in bits.netbeans.org/media (these have
not been donated, AFAIK). The list of external links from the tutorials
is available at: https://vieiro.net/netbeans/external-links.txt
== The website
Once the tool is run one can add the ~3000 generated AsciiDoc and image
files to the NetBeans website. I've created a
feature/third-donation-tutorials branch in my website clone at [2], but
have not made it a PR as of yet. You can clone this branch yourself and
run "gradlew buildSite run" to generate the website yourself in your box.
== Proposed plan
I'd appreciate you taking a look at the automatically generated
tutorials at [3] (feature/third-donation-tutorials branch and the
kb/docs subdirectories, see for instance [4]) and validating these.
The proposed plan is to
1.- fine-tune the "html-convert" tool and try to think of missing
features or improvements. Code quality is not critical as...
2.- ... the tool will be run _once_ to generate the final asciidoc
material. The tool won't be run again.
3.- include the asciidoc material in the website.
4.- start a plan to manually review the tutorials, seeing what's missing
(videos, etc.) or obsolete, and what needs updating or translating. With
the help of the Community. This can be performed with PRs against the
website or by directly editing the asciidoc in github.
As usual reviews, enhancements and improvements are most welcome.
Kind regards,
Antonio
[1]
https://github.com/apache/incubator-netbeans-tools/pull/8
[2]
https://github.com/vieiro/incubator-netbeans-website/tree/feature/third-donation-tutorials
[3]
https://github.com/vieiro/incubator-netbeans-website/tree/feature/third-donation-tutorials/netbeans.apache.org/src/content/kb/docs
[4]
Example with images:
https://github.com/vieiro/incubator-netbeans-website/blob/feature/third-donation-tutorials/netbeans.apache.org/src/content/kb/docs/java/debug-visual.asciidoc
Example with images & source code (Java syntax highlighting)
https://github.com/vieiro/incubator-netbeans-website/blob/feature/third-donation-tutorials/netbeans.apache.org/src/content/kb/docs/java/groovy-quickstart.asciidoc
Idem in the japanesse version:
https://github.com/vieiro/incubator-netbeans-website/blob/feature/third-donation-tutorials/netbeans.apache.org/src/content/kb/docs/java/groovy-quickstart_ja.asciidoc
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@netbeans.incubator.apache.org
For additional commands, e-mail: dev-h...@netbeans.incubator.apache.org
For further information about the NetBeans mailing lists, visit:
https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists
