﻿/*
	© 2013-2016 FrankHB.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file Meta.txt
\ingroup Documentation
\brief 项目元标记。
\version r1514
\author FrankHB <frankhb1989@gmail.com>
\since build 393
\par 创建时间:
	2013-03-25 00:01:48 +0800
\par 修改时间:
	2016-06-08 06:59 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::Meta
*/

// This file contains meta descriptions and formal project information.

$META:
//$configureation_for_custom_NPL_script_parser:
$parser
(
	$eval($ignore_not_impl);
	$eval($for_each $anything $in $.iterators $do_something) unfold;
);
$parser.$ __pstate;
$parser.unfold __unfold;
$parser.$.iterators __iterators;

$match_each __m;

__unfold.(__m($ctor, $dtor)) $= __pstate.behavior.ignore
	$= __m($true, $false);
__unfold __iterators.for_labeled_paragraph
(
	$HISTORY,
	$STATE
);

// See "ex.cpp" for escaped abbreviation schema.

$parser.state.style $= $natral_NPL;

// External expressions.
$lambda(_params)(...); // the lambda abstraction form;
$map(_f); // the 'map' higher order function;

// Parameters:
$inum; // issue number token, i.e. '#*';
$inum_list; // issue number list: one or more issue number tokens;
$rev; // revision token, e.g. 'b*';
$rev_list; // revision list: one or more revision tokens;
$spec; // spec token, including revision token or other documentation materials;
$spec_list; // specs list: one or more spec tokens;

// Abstract operations for dependencies:
$dep_from; // take evaluation dependence from;
$dep_all_from; // take all evaluation dependence from;
$dep_to; // put evaluation dependence to;
$effective; // only have effect on the given entity, e.g. a subset of the \
	performed namespace;
$forced; // modification mandated otherwise cause bugs (esp. ill-formed \
	program or violation to the interface specification);
$label; // label for locating in code portions;
$orig; // original source;
$redundant; // redundant dependencies;
$since; // first revision involved;

// Project stakeholders:
$dev; // issues concerned by developers, which end-users of the product can \
	observe no behavior change as long as the code has no undefined behavior \
	(including ahead-of-time build characteristics such as static assertions \
	but not runtime observable behavior like runtime assertions);
$lib; // issues only concerned with library, with no interface changed, or \
	with no deletion of interface unless some backward compatible replacements \
	are provided, as long as being confoming to the interface specification \
	(no undefined behavior, etc) and the correct behavior of external \
	environment remained, no need for library users to modify code using the \
	to adapt to the modification unless they depend on the new interface;
$design; // features changing probably only made sense to who needs to \
	reference or modify the implementation;
$src; // issues known to break public ABI but remain source compatibility;

// Project usage:
$build; // issues on build, such as build scripts and diagnostic messages;
$install; // issues on installing;
$deploy; // issues on deployment(including build environment requirement);
$debug; // issues on debugging;

// Project contents:
$comp; // features consist of dependencies with no additional work;
$doc; // for documentation target;
$fmt; // for coding format;
$mismatch($spec_list...); // for inconsistency between design and specs;
$impl; // for being used as placeholder of implementation parts;
$repo; // for repositories of version control system;
$term; // for terminology;

// Project management:
$depr_clean; // for deprecated contents cleanup;
$re($rev_list); // for same repeated operations;
$re_add($rev_list); // for additional similar repeated operations;
$re_ex($rev_list); // for repeated operations with evolution(update);
$resolve($inum_list); // for marking resolving issues;
$resolve($rev_list); // for marking resolved issues (in the issue tracker);
$revert($rev_list); // for actions reverting changes in previous revision(s), \
	with all explicit modification and effection restored to the original state.
$revert_ex($rev_list); // same for $revert except for the modification not \
	reset to the original state;
$workaround($inum_list); // for issues currently or temporarily cannot be \
	resolved through a preferred clean way for certain reasons, but exist \
	alternative ways to get being settled and work expectedly for outer \
	observers of the system;

// General features modification:
$add_features +; // features added;
$remove_features -; // features removed;
$fix_features *; // bugs of features fixed;
$modify_features /; // features modified, namely to modify features not \
	wholly for adding, removing or fixing bugs;

// General operations:
$using ^; // using;
$not !; // not;
$source_from ~; // features replaced from;
$belonged_to @;
$changed_to ->;
$moved_to >>;
$renamed_to =>;

// Abbreviations.
DD $dev $doc;
DLD $dev $lib $design;
DLI $dev $lib $impl;
DLDI $dev $lib $design $impl;
DLP $dev $lib $deploy;
DLB $dev $lib $build;


$HISTORY:

// Since b539, tracked issues are hosted on Bitbucket, see https://bitbucket.org/FrankHB/yslib/issues.
// These issues are referenced by 'issue #NUM' with NUM indicating issue number.
//	See also '$inum' for use in tags.
$resolve(#1);

// Code refactoring/fixing for quality across multiple files and probably \
	multiple revisions.
// '$end_at $revision' is the last revision of the valid remained result. \
	After this revision, the transformed content was abandoned.
// The interval is the revision(s) of transformation in progress, but not \
	necessarily containing the modifying except for the boundary. End '$now' \
	means the migration is not end yet.
$long_term_code_evolution $=
(
	"using copyright symbol '©' in head of copyright notice to conform \
		Universal Copyright Convention(UCC) for contries where Berne \
		Convention unavailable"
		$interval([$b448, $now]),
		// Head schema: "© <year> <holder>.".
		// See http://www.copyrightservice.co.uk/copyright/p14_universal_copyright_convention.
		// Conforms to: %Documentation::ProjectRules @2.7.
	"removal of spaces between years and hyphen in copyright notice"
		$interval([b441, $now]),
	"copyright notice and head formatting for original makefiles" $at b389,
	"new include header guard identifier schema" $interval([b381, $now]),
	"whitespace put between author name and mail address in files"
		$interval([b371, $now]),
	"new copyright title schema" $interval([b369, b448)) $superseded(b448),
		// Head schema: "Copyright by <holder> <year>.".
	"several postfix punctuation of comments removal" $interval([b334, b336]),
	"defined as '1' for include header guard macros" $at b334,
	"strict reversion number" $at b334,
		// See %Documentation::ProjectRules @2.2.3.
	"unified YSLib file and modules paths naming schema"
		$interval([b275, $now]),
		// Case included, except for YBase. The names is not restricted as 8.3 \
			DOS format, since ISO C++11 headers names is also not directly fit \
			for these filesystems any more.
	"Doxygen comments and file header with copyright notice" $at b170,
	"formatted comments" $interval([b166, b169]) $end_at b169
		// Doxygen used instead.
);

$ellipse_refactoring;
$ellipse_debug_assertion;

$ref $=
(
b449
(
$note "libstdc++ std::basic_string confomance"
$URL http://stackoverflow.com/questions/12520192/is-stdstring-refcounted-in-gcc-c11
$URL http://gcc.gnu.org/bugzilla/show_bug.cgi?id=52938#c8
$URL http://gcc.gnu.org/ml/gcc/2011-10/msg00115.html
$note "libstdc++ vstring"
$URL http://stackoverflow.com/questions/10463851/what-is-gccs-vstring
),
b448
(
$note "CWG 226"
$URL http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#226
$URL http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1459.html
),
b428
(
$note "G++ PR53402"
$URL http://gcc.gnu.org/bugzilla/show_bug.cgi?id=53402
),
b412
(
$note "N3652"
$URL http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html
$URL https://github.com/cplusplus/draft/blob/master/papers/n3692.html
$note "Clang++ bug 8448"
$URL http://llvm.org/bugs/show_bug.cgi?id=8448
$URL http://stackoverflow.com/questions/8984013/can-sfinae-detect-private-access-violations
),
b398 $=
(
$note "N3508"
$URL http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3508.html#synopsis
),
b351 $=
(
$note "cv-qualifier for function types"
$URL http://stackoverflow.com/questions/1117873/pointer-to-const-vs-usual-pointer-for-functions
// Also CWG 295.
),
b349 $=
(
$note "N3047"
$URL http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3047.html
// Also LWG 1260.
),
b298 $=
(
$note "access violation examples"
$URL http://stackoverflow.com/questions/5955682/boostmake-shared-causes-access-violation
$URL http://lists.cs.uiuc.edu/pipermail/cfe-dev/2011-October/017831.html
)
);

$bin_image_eq $=
(
	"platform %DS" $=
	(
		(b361r, b362r),
		(b353, b354),
		(b334r, b335r),
		(b313, b314),
		(b604r, b605r)
	)
);


$STATE:
	$LINE-WIDTH-RESTRICT 0;

// Results are collected from Workflow.*.txt reflecting current state except for following namespaces without 'merge': \
	'dep', \
	'note', \
	'report'.

dep.merge:
// $2012.
Boost(http://www.boost.org): rejected.
	Boost is too large to be a dependency before the near future.
	If possible, corresponding individual version of Boost components(e.g. non-Boost Asio at http://www.think-async.com/) should be considered to be adopted as dependencies.
// $2013-05.
Microlua(github://microlua/MicroLua-Source) @ DS: considerable, shelved.
uLibrary @ DS: rejected.
	From http://devkitpro.org/viewtopic.php?f=2&t=3192, WinterMute: "Please don't use uLibrary either, it's awful and you won't get support for it here either."
// $2013-07.
(FTGL, GLFW, FMOD) @ !DS: considerable, shelved.
Cairo: rejected.
	Reasons: http://people.mozilla.com/~roc/Samsung/Mozilla2DGraphics.pdf.
// $2013-08.
df.operators(https://github.com/d-frey/operators): considerable, shelved.
	// $2015-02: partially merged.
// $2013-10.
libmagic(https://github.com/glensc/file): rejected.
	This library implements a DSL(with BNF provided among the source files) for querying magic number database. It is heavyweight and too complex for freestanding implementations.
	Stripping the code of extended functionality(other than MIME detection needed by YFramework) out is difficult, because functions for printing and parameters for state passing are spread in the call graph deeply.
	For hosted implementations, operation system or desktop environment based implementations may provide alternative more benifical interfaces for integrating custom/user-specified information of content types.
	Also the depolying overhead of the magic databace files is significant.
	For these reasons, this library is not suitable for YFramework, though may be fit for the low level indirect implentation esp. on POSIX systems.
// $2014-09.
Boost.Trie(https://github.com/ithlony/Boost.Trie): tentatively rejected.
	This is a project of Boost GSoC 2013.
	Despite the whole Boost had been rejected before($2012), it was probable to be accepted to merge. However, it is not proper now.
	It is not being actively developed for months.
	It was considered not peer review ready, see https://groups.google.com/d/topic/boost-devel-archive/KjerA9jlLbo for some details.
	There seems to be no documentation ready.
		No stable interface is clearly stated.
		No characteristics like complexity is clearly stated and ensured.
	The standard container like 'std::map' are used directly in the data structure as members.
		Though acceptable, just a note: many operations would be limited by the QoI of the standard library.
		Many operations would be more expansive than standard library calls, and often beated the purpose to introduce a trie (to replace a 'std::set' or 'std::unordered_set', etc).
		It is also not very memory-efficient, e.g. duplicate node sizes were stored.
tx-trie(https://code.google.com/p/tx-trie/): rejected.
	It is not being actively developed for years.
	It is for paticular string type and not templated.
	There exists quality problems, e.g. macro names pollution, directly used unqualified-id of C standard library functions, memory allocation, etc.
marisa-trie(https://code.google.com/p/marisa-trie/): considerable, tentatively shelved.
	It has some similar problems of interface like tx-trie. However, it seems to be fit for other use.
// $2015-03.
dep.merge:
OpenImageIO(http://www.openimageio.org/): tentatively rejected.
	This is a library focused on image I/O.
		It actually does more, e.g. provides some ISO C99 math functions and POSIX math macros, implementation of 'array_view', etc.
		It embeds some 3rd party code to support XML, SHA1, etc.
		It also encapsulates some system-dependent operations, e.g. threads.
			The threading operations depend on Boost.Thread.
		Its interface is in C++.
			This is good to avoid name clash.
			However, the quality is not always good.
				Error handling totally bypassed exceptions (except for throwing 'std::out_of_range' from 'array_view', etc), and uses thread-specific state instead.
					This is of generally bad style and can be hard to use.
			Sometimes the interface is necessarily bloated, e.g. 'ParamValueList' can actually be an type alias rather than a class.
		The headers are a bit mess.
			There are multiple headers in the same directory doing different works. Not all of them are aiming to image I/O.
			It is somewhat difficult to use it cleanly directly without referencing some use cases.
	The license is 3-clause BSD-like.
		Though 2-clause would be better, it is good to use.
	The binary code of static library is even slightly larger than that of FreeImage for MSYS2.
		It is in doubt to shrink without giving up some functionality.
	It is lacks of GIF support, which is used by YFramework.
		So at least at current, it can not replace FreeImage.
// $2015-09.
dep.merge:
libwibble(https://packages.debian.org/sid/libwibble-dev): tentatively rejected.
	This is a package about some general/low-level C++ utilities for developers.
	The interface is not up-to-date to modern C++ style.
	The functinoality should be covered by YBase and YFramework.YCLib intentionally, though most of them are not done yet.
folly(https://github.com/facebook/folly): tentatively rejected.
	Though used productively and is under actively development, this library is not fit for YSLib as a dependency.
		The API design is awful.
			Too many functionality overlapped with the standard library, with less obvious design principles.
			Too many direct use of strongly coupled specific types in function signatures (e.g. explicit 'std::string').
		The quality of impelementation is not competitive.
		It relies on a subset of boost.
			Boost is rejected basically because it is too large. This subset is still considered large engough to be rejected.
			Though some equivalent API of them are of parts of YBase (e.g. boost.operators), it is too tricky to maintain.


todo.ceased:
// $2013-06.
Base class 'noinstance' is not necessary. Use abstract class to stop create an object of a class.

todo.deferred:
// $2013-07.
Handling FreeType error 0x26: "no charmap" and 0x40: "out of memory"(descriptions from "fterrdef.h").
Ability for selecting specific typefaces with such glyphs.
Native exceptions should be caught at proper boundary.
// $2013-09.
todo.deferred:
Wrapping '__declspec(novtable)' when '_MSC_VER >= 1100'.

todo.designated:
// $2013-04.
/ device-reqirement-analysis;
/ image-reqirement-analysis, round 2;

todo.finished:
// $2013-06.
Updating dependencies of FreeImage.
	// To make binary change small.
	// Finished @ 2013-07.

workflow.dev-dep:
// $2013-04.
For UI:
	(literal semantics, function mapping) -> NPL evaluator,
	UI layout manager -> UI designer,
	(concreate UI sessions, UI session manager) -> UI session shells,
	device abstraction -> platform surfaces,
	(YEGE, graphical layer adaptors) -> YSLib graphical APIs;

////

