From 434a9c4b9718b03a9361a25c62037f8c05e92e60 Mon Sep 17 00:00:00 2001 From: Edouard DUPIN Date: Tue, 13 Sep 2016 22:21:39 +0200 Subject: [PATCH] [DOC] first basic documentation --- doc/build.md | 38 +++++++++++-------- doc/mainpage.md | 63 +++++++++++++++++-------------- doc/read.md | 98 ++++++++++++++----------------------------------- doc/write.md | 60 ++++++++---------------------- doxy_egami.py | 8 +++- 5 files changed, 106 insertions(+), 161 deletions(-) diff --git a/doc/build.md b/doc/build.md index fda02c0..f896eca 100644 --- a/doc/build.md +++ b/doc/build.md @@ -1,14 +1,14 @@ -Build lib & build sample {#exml_build} +Build lib & build sample {#egami_build} ======================== @tableofcontents -Download: {#exml_build_download} +Download: {#egami_build_download} ========= -exml use some tools to manage source and build it: +egami use some tools to manage source and build it: -lutin (build-system): {#exml_build_download_lutin} +lutin (build-system): {#egami_build_download_lutin} --------------------- ```{.sh} @@ -18,49 +18,55 @@ lutin (build-system): {#exml_build_download_lutin} ``` -dependency: {#exml_build_download_dependency} +dependency: {#egami_build_download_dependency} ----------- ```{.sh} mkdir framework cd framework - git clone https://github.com/atria-soft/elog.git git clone https://github.com/atria-soft/etk.git - git clone https://github.com/atria-soft/ememory.git + git clone https://github.com/atria-soft/exml.git + git clone https://github.com/atria-soft/esvg.git + git clone https://github.com/atria-soft/egami.git + git clone https://github.com/generic-library/gtest-lutin.git --recursive + git clone https://github.com/generic-library/z-lutin.git --recursive + git clone https://github.com/generic-library/png-lutin.git --recursive + git clone https://github.com/generic-library/edtaa3-lutin.git --recursive + git clone https://github.com/generic-library/z-lutin.git --recursive cd .. ``` -sources: {#exml_build_download_sources} +sources: {#egami_build_download_sources} -------- ```{.sh} cd framework - git clone https://github.com/atria-soft/exml.git + git clone https://github.com/atria-soft/egami.git cd .. ``` -Build: {#exml_build_build} +Build: {#egami_build_build} ====== -library: {#exml_build_build_library} +library: {#egami_build_build_library} -------- ```{.sh} - lutin -mdebug exml + lutin -mdebug egami ``` -Sample: {#exml_build_build_sample} +Sample: {#egami_build_build_sample} ------- ```{.sh} - lutin -mdebug exml-sample + lutin -mdebug egami-sample ``` -Run sample: {#exml_build_run_sample} +Run sample: {#egami_build_run_sample} =========== ```{.sh} - lutin -mdebug exml-sample?run + lutin -mdebug egami-sample?run ``` diff --git a/doc/mainpage.md b/doc/mainpage.md index 7f11df8..60eca9a 100644 --- a/doc/mainpage.md +++ b/doc/mainpage.md @@ -1,52 +1,59 @@ -EXML library {#mainpage} -============ +EGAMI library {#mainpage} +============= @tableofcontents -What is EXML: {#exml_mainpage_what} -================== +What is EGAMI: {#egami_mainpage_what} +============== -EXML, or Ewol XML interface is a simple, small, efficient, C++ XML parser/generator that can be easily integrating into other programs. +EGAMI, or IMAGE in the oposity way is a simple library that permit to read many format of image without knolege of the specific under library API. -What it does: {#exml_mainpage_what_it_does} +What it does: {#egami_mainpage_what_it_does} ------------- -EXML parses an XML document, and builds from that a Document Object Model (DOM) that can be read, modified, and saved. +EGAMI Read some image format: + - bmp + - png + - svg -XML stands for "eXtensible Markup Language." It is a general purpose human and machine readable markup language to describe arbitrary data. -All those random file formats created to store application data can all be replaced with XML. One parser for everything. +Egami stor file format: + - bmp -http://wikipedia.org/wiki/XML +EGAMI is dependent of the STL (compatible with MacOs stl (CXX)) -There are different ways to access and interact with XML data. -EXML uses a Document Object Model (DOM), meaning the XML data is parsed into a C++ objects that can be browsed and manipulated, and then written to disk. -You can also construct an XML document from scratch with C++ objects and write this to disk. +What is the TODO list: {#egami_mainpage_todo} +---------------------- -EXML is designed to be easy and fast to learn. +Must integrate read of: + - jpeg + - webp + - gif + - tga + - yuv -EXML is dependent of the STL (compatible with MacOs stl (CXX)) +Must integrate store of: + - png + - webp -What it doesn't do: {#exml_mainpage_what_it_not_does} -------------------- +must port to use Open-cv core backend to store image (in optionnal mode) -EXML doesn't parse or use DTDs (Document Type Definitions) or XSLs (eXtensible Stylesheet Language). -What languages are supported? {#exml_mainpage_language} +What languages are supported? {#egami_mainpage_language} ============================= -EXML is written in C++. +EGAMI is written in C++. -Are there any licensing restrictions? {#exml_mainpage_license_restriction} +Are there any licensing restrictions? {#egami_mainpage_license_restriction} ===================================== -EXML is **FREE software** and _all sub-library are FREE and staticly linkable !!!_ +EGAMI is **FREE software** and _all sub-library are FREE and staticly linkable !!!_ -License (APACHE-2.0) {#exml_mainpage_license} +License (APACHE-2.0) {#egami_mainpage_license} ==================== -Copyright EXML Edouard DUPIN +Copyright EGAMI Edouard DUPIN Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -61,11 +68,11 @@ See the License for the specific language governing permissions and limitations under the License. -Other pages {#exml_mainpage_sub_page} +Other pages {#egami_mainpage_sub_page} =========== - - @ref exml_build - - @ref exml_tutorial_read - - @ref exml_tutorial_write + - @ref egami_build + - @ref egami_tutorial_read + - @ref egami_tutorial_write - [**ewol coding style**](http://atria-soft.github.io/ewol/ewol_coding_style.html) diff --git a/doc/read.md b/doc/read.md index 40398ef..a8635d7 100644 --- a/doc/read.md +++ b/doc/read.md @@ -1,80 +1,36 @@ -Read an XML content {#exml_tutorial_read} -=================== +Read file with EGAMI {#egami_tutorial_read} +==================== @tableofcontents -The first thing to do when reading or writing a XML file/stream, is to declare the Document interface +Include EGAMI +@snippet read.cpp egami_sample_include -Include exml -@snippet read.cpp exml_sample_include - -Declare document interface -@snippet read.cpp exml_sample_declare_doc +Declare image interface +@snippet read.cpp egami_sample_declare_image -Read an XML file {#exml_tutorial_read_file} +Read a Bitmap or an PNG {#egami_tutorial_read_file} +======================= + +Read a bitmap +@snippet read.cpp egami_sample_read_file_bmp + +Read a PNG +@snippet read.cpp egami_sample_read_file_png + +Read a SVG {#egami_tutorial_read_file_svg} +========== + +Read a svg +@snippet read.cpp egami_sample_read_file_svg + +Read a svg and natively rescale it: +@snippet read.cpp egami_sample_read_file_svg_rescale + + +All example file {#egami_tutorial_read_all} ================ -File to read: "read.xml" -@include read.xml - -Reading a file is done like this: -@snippet read.cpp exml_sample_read_file - -The file naming is manage by @ref etk::FSNode that provide "DATA:" start string for internal application asset. You can use external path like "./plop/file.xml" too. - - -Read an XML Stream {#exml_tutorial_read_stream} -================== - -Reading a stream is done like this: -@snippet read.cpp exml_sample_read_stream1 - -In C and C++ it is very hard to read string with the \\" then to simplify parsing of xml the parser engine support the use of simple ' interface: -@snippet read.cpp exml_sample_read_stream2 - - -Access at all Element datas {#exml_tutorial_read_folow} -=========================== - -In an exml::Element (or exml::Document) the sub-nodes are accessible threw an abstraction class stores in an element name **nodes** - -Get a node with its name: -@snippet read.cpp exml_sample_read_get_node - -Reading all file nodes: -@snippet read.cpp exml_sample_read_folow_nodes - -**note:** the itElem is a simple exml::Node that can be all the xml type. you can change the type by calling: toDocument(), toElement(), toString() ... - -In a C style mode: -@snippet read.cpp exml_sample_read_folow_nodes_c - - - -In an exml::Element (or exml::Document or exml::Declaration) the sub-nodes are accessible threw an abstraction class stores in an element name **attributes** - -Reading all Attributes of one node: -@snippet read.cpp exml_sample_read_folow_attributes - -In a C style mode: -@snippet read.cpp exml_sample_read_folow_attributes_c - -Get an attribute data: -@snippet read.cpp exml_sample_read_get_direct_attribute - - - - -In an exml::Element (or exml::Document) the internal data text can be accessible threw the interface: - -Get all the data in an element in text mode: -@snippet read.cpp exml_sample_read_get_all_under_string - - - -All example file {#exml_tutorial_read_all} -================ - -@snippet read.cpp exml_sample_read_all +@snippet read.cpp egami_sample_read_all diff --git a/doc/write.md b/doc/write.md index 4c82b14..d5fe2f3 100644 --- a/doc/write.md +++ b/doc/write.md @@ -1,61 +1,31 @@ -Write an XML content {#exml_tutorial_write} +Write an EGAMI content {#egami_tutorial_write} ==================== @tableofcontents -The first thing to do when reading or writing a XML file/stream, is to declare the Document interface +Include EGAMI +@snippet read.cpp egami_sample_include -Include exml -@snippet read.cpp exml_sample_include - -Declare document interface -@snippet read.cpp exml_sample_declare_doc +Declare image interface +@snippet read.cpp egami_sample_declare_image -Write an XML file {#exml_tutorial_write_file} -================= +Create an image with data {#egami_tutorial_write_create_image} +========================= -Write an xml tree is done like: -@snippet write.cpp exml_sample_write_file +Set image point: +@snippet write.cpp egami_sample_create_image -Write an XML Stream {#exml_tutorial_write_stream} -=================== +Write image with egami {#egami_tutorial_write_stream} +====================== -Writing a stream is done like this: -@snippet write.cpp exml_sample_write_stream - -Operation on Tree {#exml_tutorial_write_operation} -================= - -Add Node/Declaration: -@snippet write.cpp exml_sample_write_add_declaration - -Add an Node/Element: -@snippet write.cpp exml_sample_write_add_element - -Remove a Node/Element: -@snippet write.cpp exml_sample_write_rm_node +Write the data in the file: +@snippet write.cpp egami_sample_write_file_bmp -Add an attribute (simple version): -@snippet write.cpp exml_sample_write_add_attribute_simple - -Add an attribute (complex version): -@snippet write.cpp exml_sample_write_add_attribute_complex - -Remove an attribute: -@snippet write.cpp exml_sample_write_rm_attribute - -Object concept {#exml_tutorial_concept} -============== - -the exml concept is to abstract the implementation of the internal system. All the element are maped on shared memory. -Then if you asign an element to an other, it is the same. You need to clone it if you want to have new standalone element. - - -All example file {#exml_tutorial_write_all} +All example file {#egami_tutorial_write_all} ================ -@snippet write.cpp exml_sample_write_all +@snippet write.cpp egami_sample_write_all diff --git a/doxy_egami.py b/doxy_egami.py index 3657f5b..7606928 100644 --- a/doxy_egami.py +++ b/doxy_egami.py @@ -10,7 +10,13 @@ def create(target, module_name): my_module.set_title("egami: Ewol IMAGE interface abstraction") my_module.set_website("http://atria-soft.github.io/" + module_name) my_module.set_website_sources("http://github.com/atria-soft/" + module_name) - my_module.set_path(os.path.join(tools.get_current_path(__file__), module_name)) + my_module.add_path([ + module_name, + "doc" + ]) + my_module.add_sample_path([ + "sample", + ]) my_module.add_depend([ 'esvg', 'etk'