d060701a: getpwd Platform Isolation

Status	Date	Description








	2006-08-07	d060701: number sections with permalinks
	2006-08-06	d060701e: Update to include d060701j as the latest version.
	2006-08-06	d060701f: 0.42 Update the Zip archive to reflect the obsolescence of this version, with no other changes.
	2006-08-05	d060701g/h: I arranged not to use the heap or a large stack frame for buffering the entered password. Document that this was a concern and I chose to move the problem to the caller, where there is more situation-specific knowledge.
	2006-08-05	d060701g/h: We need to be specific about the conditions under which the application can be aborted by user action while getpwd is awaiting input.
	2006-08-05	d060701i: Look at the edge case of <0 results, and why it is not permissible, with the portable interface, to use this as a way of sneaking details to platform-specific callers. To do that takes a different header file. It is interesting to consider whether under-specifying the returned value is all that desirable.
	2006-08-05	d060701g/h: We have to be careful in working with size_t and edge cases with respect to integers, etc. This needs to be documented.
	2006-08-05	d060701g/h: How do we deal with locale sensitivity in character manipulations?
	2006-08-05	d060701g/h: Look at __isascii() from ISO C++ and <ctype.h> as a possible important case for filtering characters.
	2006-08-05	There needs to be a separate program for exercising the implementation _getch() and _putch() functions) to discover how these really work with keyboards, what the dependencies are, and how to properly get through the input stream.
	2006-08-05	There needs to be a place where the design decisions and related TROSTing of this effort are discussed. Some issues are the choke on buffer size, the reliance on pure ASCII, and avoidance of multi-byte and wide-character complexities and edge cases (like breaking a multi-byte character or surrogate pair). There's also a serious problem of synchronizing backspace and multi-byte characters in the buffer. These can all be about problems we are avoiding and also that must be documented in case someone decides to make a getpwd for those more-difficult settings.
	2006-08-05	d060701j: Add discussion on the page of what is being accomplished in this update, what the thinking might be, etc. This could also be a see-also to the main thread, but we don't have one of those yet.
	2006-08-05	d060701j: Make the next version of the header, with validation and other information from the API Reference. Cross-reference to the API Reference that applies.
	2006-08-04	d060701i: Include an attribution entry
	2006-07-30	d060701: There needs to be, someplace in the folio, more on organization of Zip packages for solution building (in the case of Visual Studio) and also direct building (probably using batch files on Windows platforms, other approaches for other platforms -- JavaScript? -- with some modicum of attention on managing dependencies and providing guidance for installing, building and operating the code. Ideally, there are places that can be cited and only a sketch/outline with links is needed here.
	2006-07-29	d060701f: The header file must contain information about what is allowed to change without having to revise the header/interface contract version.
	2006-07-29	d060701f: Explain the naming of the file and the document engineering principles that are being applied in this case. The principles might be on another page, or even over in an infoNote. But there is some representation here, for now. [dh:2006-08-06 This is accomplished on the API Reference, d060701i. There can be more about packaging on the new header description, d060701j, where the first use of this naming is applied.]
	2006-07-29	Once the versioned "man page" is published, link to the version from the corresponding article on the Forum. [dh:2006-08-06 That is the d060701i getpwd API Reference, and the link should be to d060701d, the page that always tracks the latest API Reference.]
	2006-07-29	Once the pages are published, link to the approach from the original article on the MSDN Forum
	2006-07-29	Incorporate the approach posted to the forum as a versioned folio page. [dh:2006-08-06 My latest thinking is that d060701b holds the latest overall approach and description material, with d060701c as the first version.]
done 0.50	2006-08-07	d060701 and d060701f/j update to version 0.50 of the next headers
done 0.50	2006-08-07	d060701: 0.50 update versions of the archived materials
done 0.50	2006-08-07	d060701i: 0.50 Add defined constants for the maximum buffer size and maximum echo field.
done	2006-08-06	d060701: Update to reflect the creation of a later header page (d060701j).
done	2006-08-06	d060701f: 0.41 Link to the replacement and report that this version is now considered obsolete.
done	2006-08-05	Update catalog to reflect 0.45 alpha version here.
done 0.45	2006-08-05	d060701d: Include d060701i as the latest version of the API Reference.
done 0.45	2006-08-05	d060701i: Change the rule on excessive input to include all recognized characters, whether or not includable in the password string.
done 0.45	2006-08-05	d060701i: Change to 0.45 alpha of the API Reference. Correct on the folio cover too.
done 0.45	2006-08-05	d060701i: Review notebook pages for changes to reflect in the revised API Reference.
done 0.40 2006-08-04	2006-07-29	Incorporate the "man page" version 0.3 from the MSDN Forum thread as a versioned folio page here. [dh:2006-08-04 The latest API Specification page will be d060701d and the initial one (0.4 alpha) will be in d060701i.]
done 0.40	2006-08-04	d060701i: Add section numbers and anchor them as permalinks.
done 0.40	2006-08-04	d060701i: Change return type to long and indicate that there are still edge cases. Invariants for the int result and the size_t parameters must be accounted for in the calling program. getpwd lacks sufficient information to apply a universally-correct standard behavior. [dh:2006-08-04 This is silly. Keep the result an int and constrain the value of maxpwd and maxfield to something reasonable, like 256 ASCII characters.]
not done	2006-08-04	d060701i: Change the prototype to return a long rather than an int.
done 0.40	2006-08-04	d060701i: Create as the starting version of the API Specification ("man") page.
done 0.45 2006-08-03	2006-07-30	d060701: Add a "see also" to the MSDN Forum thread where this all began. [dh:2006-08-05 This is in the acknowledgment already.]
done 0.45 2006-08-03	2006-07-30	d060701: Acknowledge the original inspiration for taking this journey.
done 0.45 2006-08-03	2006-07-30	d060701: Add an explanation of the coverage of the exercise, including (1) developing a stable header file that is itself fully portable among Standard C/C++ implementations, (2) developing a set of portable test programs and examples that are themselves fully portable among Standard C/C++ implementations, (3) developing a platform-independent fixture that pretends to be a getpwd implementation, and (4) developing a platform-specific implementation that remains fully encapsulated behind the contracted interface associated with the header file and its correct portable use.
done	2006-08-03	d060701f: The revision-linking link to d060701e is implemented incorrectly (it's still d060701d from the boilerplate file that I used).
done 0.40 2006-07-30	2006-07-29	Once the initial header file information is published, also publish an abbreviated version on the discussion thread, linking back to the "master" version.
done 0.40	2006-07-29	d060701f: Make a version that simply uses getpwd00.h as the alpha-beta version. It is up to developers to track these and/or go upgrade them for getpwd10.h when it is baked.
done 0.30	2006-07-29	d060701f: Include enough material so I can post this to the web site and then post an article about it on the thread.
done 0.30	2006-07-29	d060701f: Add a d060701f.txt template and go through the drill about adding it to the .zip file, etc. Make this a very simple one.
done 0.30	2006-07-29	The standalone version of the getpwd.h file should have a link to its revision history and further information. The document engineering should be established from the beginning. Because there is only one getpwd.h.txt file [is there?], we need to consider versioning it appropriately. This depends on contract identification and versioning. We need to look at that from the beginning too. [dh:2006-07-29 I chose to use getpwd00.h flavors for alpha and provisional versions, with getpwd10.h for version 1.0 of getpwd.]
done 0.30	2006-07-29	Create an initial header file text and publish it here on a versioned thread.
done	2006-07-29	d060701f: Put the header inside of a Zip file so that the version-control information is preserved. Also, this way I can use a simple name (d060701f.zip) for the container.
done	2006-07-29	d060701f: Include the little compilation test program as part of the Zip, as long as we are doing this.
done	2006-07-29	d060701f: Make sure the date-time stamp in the anchor block is updated on all changes to the page.
done	2006-07-29	d060701e: Make this the master page and include d060701f as the initial content.
done	2006-07-29	d060701f: Make this the description page for getpwd00-0.3alpha.h
done	2006-07-29	Add placeholder pages d060701d and d060701e so that we can capture the material from/for the discussion thread.
done	2006-07-29	Customize all pages of the folio to provide basic placeholder structure: d060701, d060701b, and the starting d060701c.
done	2006-07-29	Customize to support initial work items for "getpwd Platform Isolation"