﻿/*
	© 2013-2017 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 r1615
\author FrankHB <frankhb1989@gmail.com>
\since build 393
\par 创建时间:
	2013-03-25 00:01:48 +0800
\par 修改时间:
	2017-04-11 09:42 +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;
$list_param.default_separator $= ',';

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

// 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, composing a revision signature;

// 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 documentation module name or other \
	documentation materials, with optional revision token or revision signature;
$spec_list; // specs list: one or more spec tokens;

// Project stakeholders:
/*
NOTES:

The requirements of contracts imply no undefined behavior.

End-users of the project may observe behavior changes. For developers, the
contracts further includes ahead-of-time build characteristics such as static
assertions but not runtime observable behavior like runtime assertions.

Being conforming to the interface specification implies contracts on that
interface are not violated.

Expected "correct" behavior would only be achived when the corresponding
interface specifications are not violated and the behavior of external
environment remains also predicatable.

Certain kinds of modifications of the library provide explicit backward
compatibility on API and/or ABI level. If not mentioned, ABI stability is not
preserved.
If ABI remains compatibile, there would be no need to deploy new
binary code.
If API remains compatible, there would be no need for library users to modify
code using to adapt to the modification unless they depend on the new interface.
Since additions of interface might intefere with valid working code (e.g. with
SFINAE checks), so unless specified otherwise, they do not fall into the
category of not requiring the user code to be modified.
*/
$dev; // issues concerned by developers, which end-users of the product can \
	observe no behavior change as long as the contracts of the code are not \
	violated;
$lib; // issues only concerned with library, without interface changes or \
	deletion unless providing some backward compatible replacements as long as \
	the correct behavior can be expected;
$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 requirements);
$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, \
	which may not be observer behavior or features exposed by interface by \
	design;
$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;
DI $design $impl;
DLD $dev $lib $design;
DLI $dev $lib $impl;
DLDI $dev $lib DI;
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:
// To serve to the purpose of avoiding "reinventing the wheels", current libraries are considered to be merged or depended on.
// $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.
// $2014-09.
Boost.Trie(https://github.com/ithlony/Boost.Trie): tentatively rejected.
tx-trie(https://code.google.com/p/tx-trie/): rejected.
marisa-trie(https://code.google.com/p/marisa-trie/): considerable, tentatively shelved.
// $2015-03.
dep.merge:
OpenImageIO(http://www.openimageio.org/): tentatively rejected.
// $2015-09.
dep.merge:
libwibble(https://packages.debian.org/sid/libwibble-dev): tentatively rejected.
folly(https://github.com/facebook/folly): tentatively rejected.
// $2017-03:
dep.merge:
libfat 1.1.0: reviewed, partially merged, partially shelved.


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;

////

