﻿/*
	© 2013-2015 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 r1013
\author FrankHB <frankhb1989@gmail.com>
\since build 393
\par 创建时间:
	2013-03-25 00:01:48 +0800
\par 修改时间:
	2014-04-06 18:01 +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
(
	$DONE,
	$DOING,
	$NEXT_TODO,
	$TODO,
	$LOW_PRIOR_TODO,
	$FURTHER_WORK,
	$KNOWN_ISSUE,
	$TO_BE_REVIEWED_ENVIRONMENT_ISSUE,
	$RESOLVED_ENVIRONMENT_ISSUE,
	$HISTORY,
	$STATE
);

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

$parser.state.style $= $natral_NPL;

// Abstract operations for dependencies:
$dep_from; // take evaluation dependence from;
$dep_all_from; // take all evaluation dependence from;
$dep_to; // put evaluation dependence to;
$label; // label for locating in code portions;

// Project stakeholders:
$dev; // issues concerned by developers, which end-users could ignore without \
	risk if the code with no undefined behavior (including compile-time \
	characteristics such as static assertions but not runtime observative \
	behaviors like runtime assertions);
$lib; // issues only concerned with library(only implementation changing, \
	or interface modifying including no deletion unless some replacements are \
	provided, no current code would be broken (except for which has undefined \
	behavior), so no need for library users to modify code behavior using the \
	library interface to adapt to the upgrading), regaradless of output targets;
$design; // features changing probably only made sense to who needs to \
	reference or modify the implementation;

// 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);

// Project contents:
$comp; // features consist of dependencies with no additional work;
$doc; // for documents target;
$repo; // for repositories of version control system;
$term; // for terminology;

// Project management:
$depr_clean; // for deprecated contents cleanup,
$re($rev_list); // for repeated operations,
$re_ex($rev_list); // for repeated operations with evolution(update),
$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; // 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.
DLD $dev $lib $design;
DLP $dev $lib $deploy;
DLB $dev $lib $build;


// Identifiers '$known_issue(*)' indecate the earliest development stage when \
	first time of getting the the issues confirmed. Obsolete issues all \
	resolved are ignored. See $TO_BE_REVIEWED_ENVIRONMENT_ISSUE for issues to \
	be reviewed. See $RESOLVED_ENVIRONMENT_ISSUE for other resovled issues.
// Identifiers '$workaround(*)' indicate earliest development stage when first \
	time of the workaround settled.
// Identifiers '$resolved(*)' indicate earliest development stage when first \
	time of getting the issues confirmed to fixed.
// Identifier '$orig_defect' indicates that the issue was confirmed being a \
	defect of environment found by this project firstly.
// Identifier '$non_env_fix' indicates that the issue was resolved by \
	modifying project files as non-workaround rather fixing the known problem \
	of environment.
// Identifiers '$no(*)' indicate the ordinal number of issue tracking system. \
	The first issue is reserved as 'META'.


$KNOWN_ISSUE:
// Sorted by known revisions.
// There are issues that won't be fixed if no further progress for \
	implementation techniques found. Also depends on the environment.
// Identifier '$deferred' is assigned for issues being hold on.
// Identifier '$open' is assigned for open issues.
$no(3) $deferred
* $known_issue(b264) "<cmath> cannot use 'std::*' names" @ "!defined \
	%_GLIBCXX_USE_C99_MATH_TR1" @ "libstdc++ with G++ (4.6, 4.7) on devkitARM"
	@ "platform %DS" $before $future;
	// G++ 4.7.0 tested @ b301.
$no(4) $open
* $known_issue(b279) "crashing after sleeping(default behavior of closing then \
	reopening lid) on real machine due to libnds default interrupt handler \
	for power management" $since b279;
$no(9) $open
* $known_issue(b346) "vertical synchronization lacked for debug configuration \
	when console window had got focus and then clipped with the main window"
	@ "platform %MinGW32";
	// Seems to attribute to Windows GDI.
$no(12) $open
* $known_issue(b351)_2 "diagnostic message generated by \
	Clang++[-Wmismatched-tag]";
	// Though clang++ will complain for '-Wmismatched-tags', it's totally \
		safe. Only on non-comforming implementation(like Micrsoft C++) it \
		would be a problem.
$no(14) $deferred
* $known_issue(b353) "'lto1.exe : internal compiler error : \
	in lto_output_varpool_node, at lto-cgraph.c:595' when compiling with \
	-flto=jobserver" @ "project %YSTest_ARM9" @ "debug configuration"
	@ "platform %DS" ^ "G++ 4.7.1";
	// Here is a related bug report: \
		http://gcc.gnu.org/bugzilla/show_bug.cgi?id=52722 .
	// Release configuration using '-flto=jobserver' would obviously enlarge \
		the size of execution file.
$no(15) $deferred
* $known_issue(b354) "'lto1.exe: internal compiler error: \
	in lto_output_varpool_node, at lto-cgraph.c:595' when compiling with \
	-flto=jobserver" @ "project %YSTest" @ "debug configuration"
	@ "platform %MinGW32" ^ "G++ 4.7.2";
	// Seemed same to $known_issue(b353). Here is a related bug report: \
		http://gcc.gnu.org/bugzilla/show_bug.cgi?id=54118 .
	// Release configuration using '-flto=jobserver' would obviously enlarge \
		the size of execution file.
$no(22) $deferred
* $known_issue(b440) "no clean way to split constexpr with const for member \
	functions";
	// This makes something like reusing compound assignment to build binary \
		operators.
	// This is blocked by C++11, because C++1y has some loose restrictions on \
		constexpr.
	// Though Clang++ 3.3 supports for this C++1y feature currently, there is \
		no plan to migrate to C++1y because no other available \
		implementations, and this is not specified by the normative ISO C++.
$no(23) $open
* $known_issue(b444) "class %Rect assignment '= {}' ambiguity" $since b319;
	// This is a minor issue, which can be resolved by specifying 'explicit' \
		on function parameters in future version of C++.


$TO_BE_REVIEWED_ENVIRONMENT_ISSUE:
// Issues should be reviewed later and moved as resolved if possible.
// Ordered by workaround revisions and then known revision.
$no(10)
* $known_issue(b350) $workaround(b350) "Clang++ always complains about wrong \
	format when format attribute used on a function template";
	// Use attribute only for explicit instantiation of 'char' as workaround.
$no(8)
* $known_issue(b298) $orig_defect $workaround(b377)
	"sorry, unimplemented: use of 'type_pack_expansion' \
	in template with libstdc++ std::thread" @ ^ "G++ (4.6, 4.7)"
	$before $future(G++4.7.2);
	// G++ 4.7.0 tested @ b300.
	// See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=53872 .
	// Resolved by moving position of thread initialization.
	// This issue was resolved by environment fix @ G++ 4.8.
$no(18)
* $known_issue(b402) $orig_defect $workaround(b402) "'constexpr auto' causing \
	[-Wunused-variable] @ G++ 4.8.0";
	// Not tested in other versions.
	// See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57183 .
	// Workarounded by using type name explicitly instead of 'auto'.
	// G++ 4.8.1 fixes this bug, not tested.
$no(20)
* $know_issue(b407) $workaround(b407) "configuration load wrongly as 'Debug' \
	rather than 'debug' if user configuration is cleaned on VS2012";
	// Other version unconfirmed.
	// This is the default behavior, because the solution platform is not \
		selected. Set 'DS' platform and activate other configuration (i.e. 'release'),
		then reopen the IDE to resolve.
$no(11)
* $known_issue(b351)_1 $workaround(b412) "static constexpr member of same type \
	as class being defined";
	// See http://stackoverflow.com/questions/11928089/static-constexpr-member-of-same-type-as-class-being-defined and \
		http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3308.pdf .
	// G++ 4.7 would reject some code snippets. Clang++ 3.2 (trunk161531) \
		rejects even more, including code accepted by G++ such as only list \
		initialization is being used like constexpr static member in \
		"ygdibase.h".
$no(19)
* $known_issue(b406) $orig_defect $workaround(b420) "low performance of \
	freetype 2.4.12 on DS when loading UI";
	// There is a serious performance problem using on DS (about 5x longer lag \
		when first loading) unless macro %FT_CONFIG_OPTION_OLD_INTERNALS is \
		defined at freetype configuration header %ftoption.h, but it is \
		disabled from 2.4.12 by default and removed would be since 2.5 ( \
		confirmed from git repo). Neither the concrete code which cause the \
		problem can be located. So upgrading is stopped (on all platform to \
		keep one headers version), but recompiling can be performed for \
		optimization on binary size.
	// FreeType 2.5.0.1 test @ b418.
	// FreeType 2.5.0.1 without cache subsystem test @ b419.
	// See http://savannah.nongnu.org/bugs/index.php?39383 .
	// Recompiled the library with "sfnt/ttmtx.c" with header \
		"freetype/config/ftoption.h" from FreeType 2.4.11 as workaround.


$RESOLVED_ENVIRONMENT_ISSUE:
// Issues only for regressions and testing if necessary.
// Ordered by resolved reversion and then known revision.
$no(5)
* $resolved(b293) "G++ 4.5.2 fails on compiling code with defaulted move \
	assignment operator" @ $interval([b207, b221));
$no(6)
* $known_issue(b293) $resolved(b304) "G++ 4.6.1 internal error for closure \
	object in constructors" @ $interval([b253, b300));
	// G++ 4.6.2 tested @ b293.
$no(7)
* $known_issue(b293) $resolved(b315) "G++ 4.6.1 ignores non-explicit \
	conversion templates when there exists non-template explicit conversion \
	function" @ $interval([b260, b314));
$no(17)
* $known_issue(b361) $resolved(b362) $non_env_fix "linking with DLL using GNU \
	ld auto-import leads to different address across DLL and client code for \
	same function";
	// It causes event handlers of function set in DLL cannot removed in \
		client code simply using function name.
	// Resoved by explicitly using symbol visibility wrapped by macros.
$no(13)
* $known_issue(b351)_3 $resolved(b428) "Clang++ 3.2 bugs on access control"
	// Clang++ 3.2 (trunk161531) wrongly rejected valid code in "iterator.hpp" \
		and "yevt.hpp" which G++ 4.7.2 accepted.
	// Clang++ 3.3 tested, accepting code above but having trouble to compile \
		code in "ygdibase.h" which concerned with static_cast of private bases \
		in class scope and accepted by G++ 4.8.0 correctly.
	// Clang++ 3.4 (trunk186265) tested fixed.
$no(16)
* $workaround(b353) $resolved(b492) "G++ 4.7.1 wrongly treats some special \
	function as implicitly deleted" @ $interval([b353, b492));
	// This issue is a compiler bug. It is fixed in G++ 4.7.2.
	// See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=54506 for details.
	// Since devkitPro is still remained with G++ 4.7.1 @ b353, so explicitly \
		defaulted functions are used at several contexts as the workaround.
	// devkitPro G++ 4.8.2 tested fixed @ b492.
$no(21)
* $known_issue(b427) $resolved(b492) "G++ 4.7.1 of devkitPro would crash(ICE: \
	segfault) when compiling copy constructor of %YSLib::Drawing::BasicImage \
	after put the interface %IImage at the end of base class list"
	@ $interval([b427, b492));
	// OK for MinGW G++ 4.8.1.
	// devkitPro G++ 4.8.2 tested fixed @ b492.


$RESOLVED_BUG:
$no(2)
* $known_issue(b223) $resolved(b415) "corrupted loading or fatal errors on \
	loading font file with embedded bitmap glyph like simson.ttc" $since b185;
	// Freetype (2.4.6, 2.4.8, 2.4.9, 2.4.10, 2.4.11, 2.4.12) tested.
	// It is the bug of loading and rendering wrongly ignoring the format, and \
		only occured when using FreeType cache(which is the only method in \
		YSTest). FreeType is OK.


$HISTORY:

// 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 .
	"removal of spaces between years and hyphen in copyright notice"
		$interval([b441, $now]),
	"copyright notice and head formatting for makefiles"
		$interval([b389, $now]),
	"new include header guard identifier schema" $interval([b381, $now]),
	"new copyright title schema" $interval([b369, b448)) $superseded(b448),
		// Head schema: "Copyright by <holder> <year>.".
	"author mail address with whitespace per file"
		$interval([b369, $now]),
	"several postfix punctuation of comments removal" $interval([b334, b336]),
	"strict reversion number" $at b334,
	"Doxygen comments and file header with copyright notice" $at b170,
	"formatted comments" $interval([b176, b169]) $end_at b169,
	"unified YSLib file and modules paths naming schema" $interval([b275, $now])
		// Case included.
);

$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 issue 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++ bug 53402"
$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 defect 295.
),
b349 $=
(
$note "N3047"
$URL http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3047.html
// Also LWG defect 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),
	"platform %DS" (b353, b354),
	"platform %DS" (b313, b314)
);


$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.
// $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.

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;

////

