There must be a better way of putting index pages together #2579
Comments
JJ
added
build
meta
|
First, the word 'index' is used in two ways for an
My solution to JJ's question for my rewrite of the documentation system is to have a configuration file for the index. Then the documentation software writes 'landing pages' to order the documents according to the configuration file. However, having written this system, I now think that a better solution is contained in JJ's wiki proposal for a specification of the documentation system. Since the category to which a document belongs is metadata associated with the page, I think the landing page should be defined by metadata. Hence each document page would have a tag eg. But ... even if we have metadata inside each file assigning a file to a category, how are the categories to be ordered? Where is this ordering defined? There is a bigger problem, I think. The POD6 definition is about the way a single file (or pod inside a single file) is to be rendered. But the problem we have here is that we want a way of defining how a Collection of files is to be rendered. POD6 says nothing on this matter. |
|
Um, something is missing... |
|
Following a suggestion by Damian Conway, I suggest the following:
This form already compiles with Rakudo and will provide a Config block with key
|
|
Hi,
El mié., 30 ene. 2019 a las 7:45, Richard Hainsworth (<
notifications@github.com>) escribió:
Following a suggestion by Damian Conway, I suggest the following:
- The root directory contains a file called STRUCTURE.pod6
- It is of the form:
=begin pod :meta(
:sequence< Introduction Reference Tutorial FAQ >
:sources{
Introduction => {
title=> 'Pages providing various types of introduction',
subtitle => 'Text about the category',
contents => [
header => 'Runtime',
items => <
perl6
perl6run
perl6overview
>,
header => 'Compile time',
items => < file1 file2 file3 >
]
},
Reference => <
perl6rx
perl6types
perl6data
>,
})
=end pod
This form already compiles with Rakudo and will provide a Config block
with key meta
- The key sequence is converted into separate rendered (eg. html or
md) files with names as given in the sequence (eg. Introduction Reference )
- The contents of files are given by the keys of sources, with the
titles, and subtitles, if given.
- Each item in items is converted to a link to a file in the rendering
(eg., perl6run.html)
- The file collection software would include tests so that all links
point to valid rendered files, and that all rendered files have links in
the structure document.
- The Renderer can also take the files in sequence and place them in
the header as a menu (and perhaps, the category headers in the source parts
as submenus.)
I'll have to check this out more carefully, as it deserves, but off the top
of my head
* Meta information outside the file is something I'd like to avoid. If that
file contains information that is going to be used to render other files, I
don't think it's a good solution.
* I don't see the need to make it a Pod file. It's simply meta information.
* Besides, it looks like a complete redesign not only of the current
design, but also of the current, ongoing redesign(s). I really need more
time to consider it carefully.
|
|
I think it is necessary to distinguish between individual document files and the collection of document files. meta information about a single documentation file, such as its author, title, subtitle, version, etc, should be kept inside that file. But meta information about the collection of source files cannot be kept inside each source file, but should be kept inside the collection. Your original question was about 'putting index pages together'. I submit that an index page is about the whole collection, and not about any single file. For instance, we could decide that some source file should appear in the 'Reference' category after previously being in the 'Experimental' category. Or that the Language and Tutorial categories should appear in a different order. These changes have nothing to do with the files themselves, but everything to do with the structure of the collection. In the system I have already written, the configuration files are in YAML, but it seems to me that since everything else is in POD6, then the structure file should also be in POD. Otherwise, for someone else constructing a local version of the documentation, there is an extra dependency, eg., YAML. POD is already a part of the compiler. |
|
El mié., 30 ene. 2019 a las 8:43, Richard Hainsworth (<
notifications@github.com>) escribió:
I think it is necessary to distinguish between individual document files
and the collection of document files.
meta information about a single documentation file, such as its author,
title, subtitle, version, etc, should be kept inside that file.
But meta information about the collection of source files cannot be kept
inside each source file, but should be kept inside the collection.
But we're talking about a different metadata level about an artifact that
we haven't even defined, "collection of files". So I'm kinda lost here.
Your original question was about 'putting index pages together'. I submit
that an index page is about the whole collection, and not about any single
file. For instance, we could
Yep, but I was hoping the index page would be completely defined by the
items that are indexed, leaving just the appearance issues to be decided.
You're talking about something that is close, but not really: a
"navigation" page that helps you navigate through a set of (possibly
related) pages. Once again, I don't think it's the same thing, so I really
need to define what we are talking about.
decide that some source file should appear in the 'Reference' category
after previously being in the 'Experimental' category. Or that the Language
and Tutorial categories should appear in a different order. These changes
have nothing to do with the files themselves, but everything to do with the
structure of the collection.
Categories are metadata, and as such should be included in the source. If
you make document rendering depend on external metadata, all kind of hell
might break loose (as it does now).
In the system I have already written, the configuration files are in YAML,
but it seems to me that since everything else is in POD6, then the
structure file should also be in POD.
As said above, I don't see it adds anything, except you have to represent a
data structure in Perl 6 instead of JSON or YAML. You can just skip the pod
and use Perl 6. And then what you have is a real file, with real code, that
can (and will) be used in unexpected ways... It's got to be tested, too,
because code has to be tested...
Otherwise, for someone else constructing a local version of the
documentation, there is an extra dependency, eg., YAML. POD is already a
part of the compiler.
We have so many extra dependencies a new one wouldn't be noticed; even more
so if it's simply JSON instead of YAML. Still, the main point is external
metadata... for the reasons expressed in the new doc specification, I don't
like it.
|
The documentation of Perl 6 is contained in 360 files in the Not only are the 360 files (a number that is slowly increasing) contained in the same place, but they also contain references to each other. Now suppose, we were to concatenate all the pod sources into a single Pod file (which is what P2BigPage tries to do), and call the result a manual. Now there would be a single Table of Contents, and a single Index. But such a manual is difficult to manage, particularly if you only want to change one item in one subsection. It seems to me that we need to consider the whole collection as a single entity, and not just as each file separately. Like an orchard is group of fruit trees. Sometimes it is necessary to look at trees individually, but sometimes, the whole orchard needs to be looked after, eg., a wall is placed around the orchard to protect it, not walls around each tree. So the 'landing page', which is where someone goes when wanting to see what there is in the Documentation of Perl 6, is a description about the collection of the files. In fact, the existing documentation system has two files for configuring the collection, (a) type-graph.txt, which contains information about relations between abstract items inside the documentation sources, but also information about how the sources are collected (look at the way operators are gathered), (b) the file All I am suggesting is that we are explicit about where the collection meta data is kept and how it is kept. Then we can test the meta data for completeness, etc.
And the appearance is exactly where I realised that we need meta data about the whole collection, which cannot be contained in the individual source files.
Perhaps we are talking about different things, but I submit that once we agree to a concept of a collection of source files many of these disagreements will become easier to understand.
With respect, I cannot agree. CSS stylesheet are external meta and define how a document is rendered. The reason so much breaks is because the whole system is not defined, there are no tests, and the whole tool-chain is a haphazard collection of functions. I agree with you sincerely that we need to define:
|
|
Categories are metadata, and as such should be included in the source. If
you make document rendering depend on external metadata, all kind of hell
might break loose (as it does now).
With respect, I cannot agree. CSS stylesheet are external meta and define
how a document is rendered.
Well, all data is contained in the HTML structure. CSS decides how it's
rendered, but it does not decide on the content. Your idea of using P<> to
put together pages is as far as I'd go; the page itself will have content
and metadata to render that content; in our case metadata decides how
content is generated (type-graph.txt decides hos many superclasses to
include, for instance). I want to avoid that; I want all aggregation on
pages (page collections) and pages have all the metadata they need to
generate themselves.
The reason so much breaks is because the whole system is not defined,
there are no tests, and the whole tool-chain is a haphazard collection of
functions.
Correct.
I agree with you sincerely that we need to define:
- the documents as a collection, and where the meta data for the
collection is stored.
We can create meta-pages via P<> with its own metadata.
- the structure of each document in the collection, and what meta data
is permitted
Correct. The proposal in
https://github.com/perl6/doc/wiki/Document-file-specification goes in that
direction.
- how aggregates collected from the collection are used (by aggregate,
I mean 'Table of Contents', which is gathered from =head elements, and
Index which is gathered from X<> elements. Further, the system also
has two other aggregate, namely definitions collected from places where
sub role method, etc are declared.
There are also some proposals there, but they are probably not complete.
Feel free to add.
|
|
Index pages are today generated by Documentable and no longer use this. |
The problem
Right now, the manage-page-order scripts takes several minutes to run. This contributes to #2498 and to general slowing down of things when simply testing a new feature in the docs file.
Suggestions
I don't know if this will be part of #2392 , #1823 or #2542 , but it really slows things quite a bit. Since doing stuff otherwise will involve changing things that are not tested, it's probably not a good idea to do it right now until some of the stuff above is solved, but let's keep it in mind anyway.
The text was updated successfully, but these errors were encountered: