"Jonathan Turkanis" wrote:
Looking back on MoreIo library I recommend: - to prefere Iostreams for all overlapping functionality - to move the applicable rest from MoreIo into Iostreams with: - naming conventions taken from Iostreams - documentation look and feel from Iostreams
I assume you view null_buf, pointerbuf, etc. as overlapping functionality. What about 'streambuf wrapping'?
Doesn't feel to be big help but I could be easily wrong. I have no strong opinion. __________________________________________________________________ 1. overview docs:
Okay. What do you think of the pictures here: http://tinyurl.com/5v2ak? Too much detail for the introduction?
Maybe some general, high level describing structure could come first. If it can have up to three rectangles, people could keep it in short term memory while reading futher. Maybe use of colors can be reduced.
Link to "adapters.html" is broken.
Which link?
Oops. External link when not being online. __________________________________________________________________ 2. tutorial docs:
In example: in.open(634875); also stream example should be added, just to show how it is written.
I don't understand.
streambuf_facade<random_source> in(5); in.close(); in.open(634875); stream_facade<random_source> in2(random_source(5)); in2.close(); in2.open(123);
Sentence: "... and modifies it before returning it to the user." should be "... and modifies or eliminates it before returning it to the user."
Isn't elimination a type of modification?
I think this is one of disputed questions in philosophy. Non-english readers may like if explicit.
Shouldn't it have more expressive name e.g. input_filter_base? Maybe the source/sink too.
I don't follow this.
The name 'input', without namespace qualification may: - suggest full featured, ready to use class, not something needed to be extended - may clash when one uses "using namespace xyz" a lot I personally like all base classes suffixed with "_base".
filters.html link is broken.
Which link?
Tutorial, section "Filtering Output", link with text "output_filter". It points to file "filters.html", with superfluous 's' at the end of filename.
Generally, tutorial may be sprinkled with few more overcommented code snippets. They may be hide-able. Other docs won't suffer having them too.
Okay. What do you mean by hideable? I'm hoping not to have to use any javascript except for the menu.
Exactly that. Javascript powered "Show Example"/"Hide Example" code snippet. __________________________________________________________________
4. docs: all <img> elements should have their width/height set in HTML
For slow connections, I guess?
For people who switched off images by default. __________________________________________________________________
5. concepts docs: all concepts here can be also listen in table, sorted and with one line info.
The individual concepts should be added as sub tree into left panel. Dtto compression filters, etc. Every page should be accessible from left panel.
I'll try to do this, but I might find that the menu is so big it takes too long to load.
I got confused seeing pages in right panel for whom there was no left panel item. It got me uneasy feeling I'll surely miss something. __________________________________________________________________
11. A collection of useful stream(buffer)s could be added into library, so they are handy to users:
- repeater (some sequence of characters over and over) This one could ideally accept syntax used inn Boost.Assign. It would allow to easily create complex but predictable test data structures.
Could you elaborate?
Thinko with Boost.Assigne. I meant something like: repeater_stream(repeat(2, 'a', 'b', 'c', 'd', repeat('e', 4)), 'f', 'g'); which would produce sequence: a, b, c, d, e, e, e, e, a, b, c, d, e, e, e, e, f, g and again The syntax is secondary, main point is that the generated data could be typed easily.
- 'a switcher'. Something what sends data into another stream but has method switch_to_other_stream(s). E.g. for circular logs.
Doable, but presents some problems with buffer synchronization. There is currently no generic sync() function or Synchronizable concept.
13. Possible feature of library
It would be nice to be able to 'send a command' down the stream and have some part of chain picking it up and executing. This way sender would not need to know anything about current chain structure.
Similarly one can imagine events going upstream. If anyone handles them: OK, if not they will be ignored.
Sounds interesting. I believe this would have to rely on runtime rather
Maybe this could be added (with Flush name)? __________________________________________________________________ than
compile-time polymorphism. I'll think about it.
__________________________________________________________________ 14. May it be possible to add "synchronize panels" button into left panel? If clicked, it would expand and highlight item in left panel for currently opened page in right panel.
The [link to this page] button already expands the tree to the current
Yes, maybe something typeless: x_stream s; unsigned invoked_count = s.send_command("cmd name", boost::any& parameter); s.register_event_handler("event name", boost::function<void, stream_base*> parameter); s.unregister_event_handlers("event name"); x_stream { bool on_command(const char* cmd, boost::any& parameter) { .... invoke_event("event_name"); send_command("other command downstream", parameter); .... return true; // continue with this command downstream } }; page, if
the tree contains a link to the current page. I guess highlighting would be easy enough to do. I'm afraid some would find this annoying.
15, cloable.html: it should be explained (+ example) what 'notification' here means.
How's this: A Closable filter or resource receives notifications -- via
I noticed this button only now. When I am on page not listed in left panel it just does left panel refresh. Maybe it could at least pick 'parent' or 'related' page in left panel. __________________________________________________________________ the
function <A HREF='...'>boost::io::close</A> --immediately before a containing stream or stream buffer is closed.
I have uneasy feeling about the word 'notification'. Maybe "When you close stream, filters implementing Closeable concept will have their member function close() called" or so. /Pavel