Human Readable Titles

[smizell]

As I'm working with ALPS, the one thing I feel that I'm missing is a way to provide a human-readable value for the document and descriptors.

• Right now, other than the description—which feels more long-form to me—there is no real way to provide the title of what an actual profile is. In the example in the spec, I feel like I'd like something like "Contact List" to display at the top of the page.
• Same goes for descriptors. I can show the id, but that is limited.
• When descriptors have href instead of ID, I have no way of telling the user what the profile is for. I would like to have a link that says "Person" that the user can click to view or load in the person profile. Right now, I'm just going to put "Descriptor." This means I really can only display the URL or something generic.

I suppose this could be either an attribute on alps or descriptor or it could be its own element. The former feels simplest.

[fosrias]

Just use URL introspection and it will be whatever is on the end as the title/name of the profile. That is a reliable way to handle this. :stuck_out_tongue_winking_eye:

[smizell]

Just to add, when the href is to a descriptor within the page, you'd still need a title on the descriptor.

I can see a benefit of introspecting, as you have a single source of truth for the title. But I can think of a profile that links to several descriptors. Trade off I guess.

I'm building something that will display a profile in HTML, so you can browse it in the browser. Going to allow for following link to the page or transcluding to see how it fits inline.

[filip26]

Hi @smizell , what about to display a content of 'doc' element attached to a descriptor or to a profile?

e.g.

<!-- a hypermedia control for returning contacts -->
<descriptor id="search" type="safe" rt="contact">
  <doc>
    Simple hypermedia control for getting a list of contacts
  </doc>
  <descriptor id="name" type="semantic">
    <doc>
      Input for search form
    </doc>
  </descriptor>
</descriptor>

HTML link:

<a href="...#search">Simple hypermedia control for getting a list of contacts</a>
...
<a href="...#name">Input for search form</a>

[smizell]

Hi @filip26 👋

The difference for me with doc is that:

1. It might be long
2. It might be a different type than plain text

I see Mike has proposed with #87. I'll add a couple of comments there on his specific idea, as I think it's what I was thinking.

[mamund]

i want to make sure runtime parsers can determine whether the description is to be displayed at runtime (e.g. text attribute) or used within design/build-time documentation (doc element). and the title is even unique in this case. title might be displayed either at runtime and/or design/build documentation.

let's make it easy to author and interpret documents. HTML has done this very well already (using title element and text attributes).