On Sunday, October 4, 2015, Felix Schumacher < felix.schumac...@internetallee.de> wrote:
> Hi all, > > I have spend a lot of time lately going through the docs for jmeter and > especially looking at the markup side of the documentation. > > I have noticed a few things, that could be (hopefully) improved. > > Code examples > --------------------- > The code examples are all treated as plain text. There is no further > markup to differentiate a shell script from an xml fragment or a java > source code example. > > Maybe we could use a javascript library like > https://github.com/google/code-prettify? We would have to add an language > attribute to each of our source code examples and extend the style sheets. > > +1 > Layout of Menu-paths and key combos > --------------------------------------------------- > Paths through menu like structures and combination of keys are text only. > I propose to add markup (like in docbook) for this. > > +1 > Notes > -------- > Notes can be used for different use cases like warnings or infos. I think > it would be nice to have an attribute on those notes to make them > distinguishable. The style of the note could reflect that attribute. > > +1 > Icons with fonts > --------------------- > Fonts like https://fortawesome.github.io/Font-Awesome/ provide nice > looking symbols, that scale well. Should we include such a font and use the > symbols for notes, bugs, ...? Would it be a problem, if the font had a non > apache license? > > possibly as doc is distributed as part of project > PDF files > ----------- > There are a few pdf files linked on the web page. Should we convert them > to xml? I don't think we would really loose anything. On the other hand the > xml->html files would be better searchable by search sites. We could link > to the original pdf files, if we want to keep them. > > +1, having them in pdf makes it harder to update the docs, at least in my experience > Usage of the different style sheets > ---------------------------------------------- > The web page and the "printable" pages are generated by different style > sheets. As far as I can see, the "printable" pages are used by jmeter's > internal doc system. Is there any other usage for those pages? Not as far as I know. > > If not, we could strip the number of generated "printable" files further, > since I haven't seen a way to show any page except the > usermanual/component_reference and usermanual/functions pages. > > The web pages should be printable with the latest additions in trunk (at > least on firefox and chrome). > > What do you think? Maybe it would even be better in jmeter to open directly the web docs in browser as we do it for templates instead of having a swing component for it. > > Regards, > Felix > > > > -- Cordialement. Philippe Mouawad.
